From 5473b40a368ce6234d675f33143bd507941b39e9 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 5 Jun 2026 17:10:48 -0700 Subject: [PATCH 1/4] docs: refresh v0.0.60 release notes --- .../references/inference-options.md | 5 +- .../nemoclaw-user-deploy-remote/SKILL.md | 4 +- .../references/install-openclaw-plugins.md | 3 + .../skills/nemoclaw-user-get-started/SKILL.md | 2 +- .../references/quickstart-hermes.md | 66 ++-- .../nemoclaw-user-manage-sandboxes/SKILL.md | 4 +- .../references/install-plugins-hermes.md | 3 + .../references/runtime-controls.md | 1 + .../references/release-notes.md | 10 + .../references/architecture.md | 7 +- .../references/commands.md | 87 +++-- .../references/network-policies.md | 3 +- .../references/troubleshooting.md | 32 +- docs/about/release-notes.mdx | 10 + skills/nemoclaw-user-agent-skills/SKILL.md | 83 ++++- .../references/agent-skills.md | 83 ----- .../SKILL.md | 200 +++++------ .../references/inference-options.md | 325 +++++++++++++++++- .../references/set-up-sub-agent.md | 32 +- .../references/switch-inference-providers.md | 181 ++++++---- .../references/tool-calling-reliability.md | 58 ++-- .../references/use-local-inference-details.md | 151 -------- .../nemoclaw-user-configure-security/SKILL.md | 7 +- .../references/best-practices.md | 128 +++++-- .../references/credential-storage.md | 40 ++- .../references/openclaw-controls.md | 10 +- skills/nemoclaw-user-deploy-remote/SKILL.md | 101 +++--- .../references/brev-web-ui.md | 12 +- .../references/install-openclaw-plugins.md | 57 ++- .../references/sandbox-hardening.md | 61 ++-- skills/nemoclaw-user-get-started/SKILL.md | 116 ++++++- .../references/prerequisites.md | 29 +- .../references/quickstart-details.md | 165 --------- .../references/quickstart-hermes.md | 119 ++++--- .../references/windows-preparation.md | 48 ++- skills/nemoclaw-user-manage-policy/SKILL.md | 123 ++++--- .../references/approve-network-requests.md | 14 +- .../customize-network-policy-details.md | 13 - .../references/integration-policy-examples.md | 220 ++++++------ .../nemoclaw-user-manage-sandboxes/SKILL.md | 193 ++++++----- .../references/backup-restore.md | 206 +++++++---- .../references/install-plugins-hermes.md | 117 +++++++ .../references/lifecycle-details.md | 26 -- .../references/messaging-channels.md | 166 +++++---- .../references/runtime-controls.md | 81 +++-- .../references/workspace-files.md | 51 ++- skills/nemoclaw-user-monitor-sandbox/SKILL.md | 74 +++- skills/nemoclaw-user-overview/SKILL.md | 10 +- .../references/ecosystem-hermes.md | 93 +++++ .../references/ecosystem.md | 16 +- .../references/how-it-works.md | 67 +++- .../references/overview.md | 48 ++- .../references/release-notes.md | 91 ++++- skills/nemoclaw-user-reference/SKILL.md | 2 +- .../references/architecture.md | 7 +- .../references/commands.md | 89 +++-- .../references/network-policies.md | 3 +- .../references/troubleshooting.md | 32 +- 58 files changed, 2444 insertions(+), 1541 deletions(-) delete mode 100644 skills/nemoclaw-user-agent-skills/references/agent-skills.md delete mode 100644 skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md delete mode 100644 skills/nemoclaw-user-get-started/references/quickstart-details.md delete mode 100644 skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md create mode 100644 skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md delete mode 100644 skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md create mode 100644 skills/nemoclaw-user-overview/references/ecosystem-hermes.md 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 8ca68d7d14..c54a6d9032 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -307,7 +307,7 @@ Managed vLLM uses these profiles: | Host profile | Default model | |---|---| | DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` | -| DGX Station | `Qwen/Qwen3.6-27B-FP8` | +| DGX Station | `deepseek-ai/DeepSeek-V4-Flash` | | Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | **Note:** @@ -344,7 +344,8 @@ Recognized slugs are: | Slug | Hugging Face model | Notes | |---|---|---| -| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on the DGX Station profile | +| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Default on the DGX Station profile | +| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Supported override | | `qwen3.6-35b-a3b-nvfp4` | `nvidia/Qwen3.6-35B-A3B-NVFP4` | Default on the DGX Spark profile | | `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile | | `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance | diff --git a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md index cb0a62547b..9885238e64 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-deploy-remote" -description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." +description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw dockerignore, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." license: "Apache-2.0" --- @@ -145,7 +145,7 @@ nemoclaw deploy ## References -- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox. +- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox, including `.dockerignore` handling for custom build contexts. - **Load [references/brev-web-ui.md](references/brev-web-ui.md)** when a user wants to try NemoClaw without installing the CLI, or asks how to get started on Brev. Guides users through deploying NemoClaw with the Brev web UI. - **Load [references/sandbox-hardening.md](references/sandbox-hardening.md)** when reviewing sandbox image security controls, auditing capability drops, or looking up the runtime resource limits. Includes the sandbox container image hardening reference, covering Docker capabilities and process limits. 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 4094f9a924..6f8e721920 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 @@ -13,6 +13,8 @@ The supported NemoClaw path for OpenClaw plugins is to bake the plugin into a cu Put the Dockerfile and everything it needs to `COPY` in one directory. `nemoclaw onboard --from ` uses the Dockerfile's parent directory as the Docker build context. +Add a `.dockerignore` next to the Dockerfile to exclude local caches, generated artifacts, model files, or other paths that are not needed by the image build. +NemoClaw still applies its own secret-safety exclusions for credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` negates them. ```text my-plugin-sandbox/ @@ -67,6 +69,7 @@ These are the most common places where plugin installation gets mixed up with ot - Do not use `nemoclaw skill install` for OpenClaw plugins. That command only installs `SKILL.md` agent skills. - Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend to send that whole directory as the Docker build context. +- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. - Keep plugin dependencies in the build stage or plugin directory; avoid copying unrelated host files into the sandbox image. diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index 0cc6f4005b..c720ad2d2c 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -260,7 +260,7 @@ openclaw tui ## References -- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes API endpoint. +- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes dashboard and API endpoint. - **Load [references/prerequisites.md](references/prerequisites.md)** when verifying prerequisites before installation. Lists the hardware, software, and container runtime requirements for running NemoClaw. - **Load [references/windows-preparation.md](references/windows-preparation.md)** when preparing a Windows machine for NemoClaw, enabling WSL 2, configuring Docker Desktop for Windows, or troubleshooting a Windows-specific install error. Covers Windows-only preparation steps required before the Quickstart. 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 d0b15db496..4717cf5018 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -20,18 +20,19 @@ export NEMOCLAW_AGENT=hermes curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -If a headless host needs to expose the Hermes API through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. -Use the externally reachable origin for port `8642`, without the `/v1` path. -NemoClaw derives the forwarded port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final OpenAI-compatible base URL with `/v1` in the ready summary. +If a headless host needs to expose the Hermes dashboard through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. +Use the externally reachable origin for the dashboard port `18789`. +NemoClaw derives the forwarded dashboard port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final dashboard URL in the ready summary. +The OpenAI-compatible API remains available separately on port `8642`. ```bash export NEMOCLAW_AGENT=hermes -export CHAT_UI_URL="https://hermes.example.com:8642" +export CHAT_UI_URL="https://hermes.example.com:18789" curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -For SSH local port forwarding to `127.0.0.1:8642`, leave `CHAT_UI_URL` unset. -Do not append an OpenClaw `#token=` fragment to the Hermes URL. +For SSH local port forwarding to `127.0.0.1:18789`, leave `CHAT_UI_URL` unset. +Do not append an OpenClaw `#token=` fragment to the Hermes dashboard URL. Hermes API clients authenticate with the bearer token from the generated Hermes environment instead of an OpenClaw dashboard URL token. If NemoClaw is already installed, start Hermes onboarding directly. @@ -86,19 +87,11 @@ 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 API endpoint. -Hermes exposes an OpenAI-compatible API on port `8642`, not a browser dashboard. -To also launch the native Hermes web dashboard, opt in before onboarding: - -```bash -export NEMOCLAW_HERMES_DASHBOARD=1 -nemohermes onboard -``` - -The dashboard uses port `9119` by default. -Set `NEMOCLAW_HERMES_DASHBOARD_PORT` before onboarding to choose a different port. -Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` to enable Hermes' optional in-browser TUI tab. -For upstream dashboard features, refer to the [Hermes web dashboard documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard). +When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes dashboard 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 builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`. +Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text ────────────────────────────────────────────────── @@ -109,13 +102,9 @@ Model: nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) Access - Hermes Agent OpenAI-compatible API - Port 8642 must be forwarded before connecting. - http://127.0.0.1:8642/v1 - - Hermes Agent Web dashboard - Port 9119 must be forwarded before opening this URL. - http://127.0.0.1:9119/ + Hermes Agent Dashboard + Port 18789 must be forwarded before opening this URL. + http://127.0.0.1:18789/ Terminal: nemohermes my-hermes connect @@ -144,9 +133,21 @@ To chat with the agent from a terminal, follow these steps: hermes ``` +## Open the Dashboard + +The onboard flow starts the dashboard port forward automatically. +Open the dashboard from the host: + +```console +$ nemohermes my-hermes dashboard-url --quiet +http://127.0.0.1:18789/ +``` + +Hermes handles dashboard sessions itself, so this URL does not include an OpenClaw `#token=` fragment. + ## Check the API Endpoint -The onboard flow starts the port forward automatically. +The onboard flow also starts the API port forward automatically. Check the health endpoint from the host to confirm that the Hermes API is reachable. ```bash @@ -163,17 +164,6 @@ Configure an OpenAI-compatible client with the base URL `http://127.0.0.1:8642/v Hermes uses API header authentication for client requests. Do not append an OpenClaw `#token=` URL fragment to the Hermes endpoint. -## Open the Optional Dashboard - -When you set `NEMOCLAW_HERMES_DASHBOARD=1` during onboarding, NemoClaw starts `hermes dashboard --no-open` inside the sandbox and forwards `http://127.0.0.1:9119/` on the host. -The API endpoint remains separate on `8642`. - -If the dashboard forward is missing after a reboot or terminal restart, start it again: - -```bash -openshell forward start --background 9119 my-hermes -``` - Treat the dashboard as a local management UI. Avoid exposing it on shared or public networks unless you put it behind your own access controls. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md index 7802405ca6..9cb897f094 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -1,6 +1,6 @@ --- name: "nemoclaw-user-manage-sandboxes" -description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." +description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemohermes dockerignore, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." license: "Apache-2.0" --- @@ -276,7 +276,7 @@ For a full comparison of the two forms, including what they fetch, what they tru - **[references/runtime-controls.md](references/runtime-controls.md)** — Single page that answers what can change at runtime versus what requires a rebuild for NemoClaw sandboxes. - **Load [references/backup-restore.md](references/backup-restore.md)** when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds. Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds. - **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, WeChat, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands. -- **[references/install-plugins-hermes.md](references/install-plugins-hermes.md)** — Explains how to install Hermes plugins in NemoClaw-managed sandboxes. +- **Load [references/install-plugins-hermes.md](references/install-plugins-hermes.md)** when users ask how to install, build, or configure Hermes plugins under NemoClaw. Explains how to install Hermes plugins in NemoClaw-managed sandboxes, including custom Dockerfile build-directory layout and `.dockerignore` handling. - **Load [references/workspace-files.md](references/workspace-files.md)** when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state. Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts. ## Related Skills diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md index 31f1903af6..4e3deaab2c 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md @@ -24,6 +24,8 @@ It uploads skill instructions and refreshes skill discovery, but it does not ins Put the custom Dockerfile and everything it needs to `COPY` in one directory. `nemohermes onboard --from ` sends the Dockerfile's parent directory as the Docker build context. +Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context. +NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them. ```text my-hermes-plugin-sandbox/ @@ -105,6 +107,7 @@ These are the most common places where Hermes plugin installation gets mixed up - Do not install Hermes plugins into `/sandbox/.openclaw/extensions`; that path is for OpenClaw plugins. - Do not remove `/sandbox/.hermes/plugins/nemoclaw`; NemoClaw depends on that plugin for managed Hermes behavior. - Do not put the Dockerfile in a broad directory unless you intend to send that whole directory as the Docker build context. +- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. - Do not assume OpenShell policy allows Python package downloads during runtime by default. ## Next Steps diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md b/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md index 4e13098c3e..e5e026974b 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md @@ -22,6 +22,7 @@ The table below maps each commonly changed item to the layer that owns it and th | Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `nemoclaw channels stop ` then rebuild | | Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | | Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | +| Default OpenClaw workspace template seed (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`) | Locked at first sandbox boot. Re-onboard required to change the bake-time choice. | Set `NEMOCLAW_MINIMAL_BOOTSTRAP=1` before `nemoclaw onboard` to skip default template seeding for new/pristine workspaces. **Does not delete files already present.** Partial mitigation for #2598 (cuts ~3k tokens of project-context overhead off OpenClaw's per-turn bootstrap injection). | | Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | | Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | | Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index b41cd6022d..77747019bf 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -4,6 +4,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.60 + +NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards: + +- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to Architecture (use the `nemoclaw-user-reference` skill). +- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from ` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). +- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). + ## v0.0.59 NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics: diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md index 07bbfc2ba9..62c053c186 100644 --- a/.agents/skills/nemoclaw-user-reference/references/architecture.md +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -68,8 +68,11 @@ graph LR The logical diagram above shows how components relate. This section shows what actually runs where on the host. NemoClaw's default Docker-driver topology does not place the sandbox in an embedded k3s cluster. -On Linux and Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. -The gateway normally runs as a host process; Linux hosts that need the gateway compatibility patch may run the same gateway binary inside a small container. +On Linux, NemoClaw configures and restarts the package-managed OpenShell gateway user service when it is installed, then creates the sandbox as a Docker container. +NemoClaw treats that service as authoritative only when `systemctl --user show openshell-gateway` reports a package/vendor unit path and an `openshell-gateway` `ExecStart`. +Per-user units, partial units, and user-manager or bus outages do not take over gateway ownership; NemoClaw falls back to the standalone gateway process used by earlier installs. +That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. +On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index 5beb179d4b..cf67f88a68 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -33,7 +33,7 @@ OpenClaw-specific sections below describe the `/nemoclaw` slash command, the Ope Use `nemohermes` for the Hermes variant. It selects Hermes by default during onboarding and for other commands. Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. -Hermes-specific sections below describe the OpenAI-compatible API endpoint, optional Hermes dashboard, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. +Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. ```bash nemohermes onboard # selects Hermes by default @@ -173,6 +173,9 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `bal NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` +Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. +Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. + `NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets. The default is `suggested`, which is *additive*. Onboarding applies tier defaults and preserves any presets you previously added with [`nemoclaw policy-add`](#nemoclaw-name-policy-add) across re-onboards. @@ -299,9 +302,10 @@ The poll count is clamped to a minimum of `1` so the probe always runs at least Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. -Onboarding skips common large directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. -It also skips credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`. -Other build outputs such as `dist/`, `target/`, or `build/` are still included. +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. 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. @@ -606,10 +610,35 @@ Warnings do not make the command fail. Failed checks exit non-zero so scripts can use `doctor` as a readiness gate. Use `--json` for machine-readable output. + + +For OpenClaw sandboxes, `doctor` also checks the mutable config permission contract. +If `openclaw doctor --fix` was run inside the sandbox, it can tighten `/sandbox/.openclaw` and `openclaw.json` to a single-user `700/600` layout, which stops the gateway from persisting config changes. +`doctor` reports this as a `Config permissions` warning; pass `--fix` to restore the group-writable `2770/660` contract without rebuilding. +Restarting the sandbox repairs the same drift automatically. + +```bash +nemoclaw my-assistant doctor [--json | --fix] +``` + +| Flag | Description | +|------|-------------| +| `--json` | Emit the report as JSON | +| `--fix` | Restore the mutable OpenClaw config permission contract if it was tightened. Mutually exclusive with `--json` | + + + + ```bash nemoclaw my-assistant doctor [--json] ``` +| Flag | Description | +|------|-------------| +| `--json` | Emit the report as JSON | + + + ### `nemoclaw logs` View sandbox logs. @@ -628,7 +657,9 @@ nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since -Print the authenticated OpenClaw dashboard URL for a running sandbox. +Print the browser dashboard URL for a running sandbox. +For OpenClaw sandboxes this includes the authenticated URL fragment. +For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL. Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session. ```bash @@ -647,14 +678,22 @@ URL=$(nemoclaw my-assistant dashboard-url --quiet) Treat the authenticated dashboard URL like a password. Do not log it, share it, or commit it to version control. +This warning applies when the command prints an OpenClaw tokenized URL. -`dashboard-url` is not applicable to Hermes sandboxes because Hermes exposes an OpenAI-compatible API endpoint instead of the OpenClaw dashboard URL. -Use `nemohermes my-assistant status` to find the forwarded API endpoint. -The Hermes API remains on port `8642` and uses `/v1` for OpenAI-compatible clients. -If you enabled `NEMOCLAW_HERMES_DASHBOARD=1`, use the optional Hermes dashboard port from the status output instead. +Print the browser dashboard URL for a running Hermes sandbox. +Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw `#token=` fragment. +The built-in dashboard is forwarded on port `18789` by default. + +```bash +nemohermes my-assistant dashboard-url +nemohermes my-assistant dashboard-url --quiet +``` + +The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for OpenAI-compatible clients. +Use `nemohermes my-assistant status` to see both the dashboard and API endpoints. @@ -1373,6 +1412,15 @@ nemoclaw tunnel stop `nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`. +### `nemoclaw tunnel status` + +Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +The output reports whether cloudflared is running, stopped, or stale, and includes the same recovery hint used by `nemoclaw status`. + +```console +nemoclaw tunnel status +``` + ### `nemoclaw start` **Warning:** @@ -1548,7 +1596,7 @@ Earlier releases only stopped `openshell forward` processes, so those orphans ac 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 PID files, SQLite data, audit logs, and VM-driver state. +On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-driver gateway SQLite data, audit logs, VM-driver state, and standalone-fallback gateway PID files. | Flag | Effect | |---|---| @@ -1690,15 +1738,14 @@ For OpenClaw, `NEMOCLAW_DASHBOARD_PORT` controls the OpenClaw dashboard forward. -For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the OpenAI-compatible API forward. -For Hermes sandboxes, `NEMOCLAW_HERMES_DASHBOARD=1` starts the native Hermes dashboard separately from the OpenAI-compatible API. -The Hermes API remains on port `8642`; the optional browser dashboard uses `NEMOCLAW_HERMES_DASHBOARD_PORT`. +For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the built-in dashboard forward, which defaults to `18789`. +The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for API clients. +Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-browser TUI tab. | Variable | Default | Service | |----------|---------|---------| -| `NEMOCLAW_HERMES_DASHBOARD` | 0 | Optional Hermes native web dashboard (`1`, `true`, `yes`, or `on` enables it) | -| `NEMOCLAW_HERMES_DASHBOARD_PORT` | 9119 | Optional Hermes native web dashboard forward port | -| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab when the dashboard is enabled | +| `NEMOCLAW_DASHBOARD_PORT` | 18789 | Hermes built-in dashboard forward port | +| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab | @@ -1725,7 +1772,7 @@ Set them before running `nemoclaw onboard`. | `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | | `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-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_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_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). | @@ -1830,9 +1877,9 @@ These flags toggle optional behaviors during onboarding; set them before running | `NEMOCLAW_SANDBOX_GPU` | `auto`, `1`, or `0` | Controls sandbox GPU passthrough during onboarding. `auto` enables GPU passthrough when an NVIDIA GPU is detected, `1` requires GPU passthrough, and `0` forces CPU-only sandbox creation. | | `NEMOCLAW_SANDBOX_GPU_DEVICE` | OpenShell GPU device selector | Selects the GPU device passed with `openshell sandbox create --gpu-device`. Requires explicit sandbox GPU enablement with `NEMOCLAW_SANDBOX_GPU=1` (or `--sandbox-gpu` for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in. | | `NEMOCLAW_DOCKER_GPU_PATCH` | `0` to disable, anything else to keep the default | Controls the Linux Docker-driver GPU sandbox compatibility patch. Set to `0` only as an escape hatch when the patch fails and you need onboarding to continue without patching the GPU sandbox container. | -| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver gateway. Defaults to the binary next to `openshell`, then common install paths. | -| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary passed to the Linux Docker-driver gateway supervisor. Defaults to the binary next to `openshell`, then common install paths. | -| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway pid file and SQLite state directory. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. | +| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. | +| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. | +| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. | | `NEMOCLAW_AUTO_FIX_FIREWALL` | `1` to enable | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs `sudo -n` only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command. | | `NEMOCLAW_WECHAT_QUIET` | `1` to enable | Silences the `[wechat]` diagnostic lines printed during the host-side WeChat QR login (poll status, IDC redirects, swallowed gateway errors), which are visible by default while the experimental WeChat path stabilizes; set `1` once the flow is reliable in your environment. | diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index de3517a690..99dabfc705 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -76,7 +76,8 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER`: NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` -If the value does not match a known tier, onboarding exits with an error listing the valid options. +Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. +If a non-blank value does not match a known tier, onboarding exits before preflight with an error listing the valid options. ### Inference diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index cdafbeb91a..6825c8152f 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -837,7 +837,37 @@ Do not treat a failed `doctor --fix` run as proof that the Discord gateway path If `openclaw doctor` reports that it moved Telegram single-account values under `channels.telegram.accounts.default`, rerun onboarding and rebuild the sandbox rather than trying to patch `openclaw.json` in place. Current NemoClaw rebuilds bake Telegram in the account-based layout and set Telegram group chats to `groupPolicy: open`, which avoids the empty `groupAllowFrom` warning path for default group-chat access. -### Discord bot logs in, but the channel still does not work +### `openclaw doctor --fix` tightened config permissions and the gateway can no longer save config + +In a mutable NemoClaw sandbox, the gateway UID and the sandbox UID share the `sandbox` group, so `/sandbox/.openclaw` is setgid and group-writable (`2770`) and `openclaw.json` is group-writable (`660`). +OpenClaw's `openclaw doctor --fix` enforces its own single-user `700/600` layout, so running it inside the sandbox strips group write and breaks gateway-side config writes (for example, control-UI toggles that mutate `openclaw.json`). + +Repair the mutable contract without rebuilding: + +```bash +nemoclaw doctor --fix +``` + +`nemoclaw doctor` reports the drift as a `Config permissions` warning, and `--fix` restores `2770/660`. +Restarting the sandbox repairs the same drift automatically, and NemoClaw's own `rebuild` re-applies the contract after its post-upgrade `openclaw doctor --fix` step. + +When verifying gateway write access by hand, step down to the gateway UID with the image's installed mechanism so the `sandbox` group membership is initialized: + +```bash +setpriv --reuid=gateway --regid=gateway --init-groups -- sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json' +# or, where setpriv is unavailable: +gosu gateway sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json' +``` + +Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gateway's supplementary groups the same way, so a group-write probe can spuriously report `EACCES` even when the mutable contract is intact. + +A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: + +- **Mutable default (shields down):** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. +- **Shields up (locked from the host with `nemoclaw shields up`):** `openclaw.json` becomes `444 root:root` and the config dir becomes `755 root:root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). +- **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart. + +## Discord bot logs in, but the channel still does not work Separate the problem into two parts: diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index 917d7dbfad..dd7a932f39 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -13,6 +13,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.60 + +NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards: + +- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to [Architecture](../reference/architecture). +- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from ` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to [NemoClaw Inference Options](../inference/inference-options). +- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `$$nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). +- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to [Security Best Practices](../security/best-practices). + ## v0.0.59 NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics: diff --git a/skills/nemoclaw-user-agent-skills/SKILL.md b/skills/nemoclaw-user-agent-skills/SKILL.md index fd12b0566d..fca8d94d8c 100644 --- a/skills/nemoclaw-user-agent-skills/SKILL.md +++ b/skills/nemoclaw-user-agent-skills/SKILL.md @@ -3,8 +3,87 @@ name: "nemoclaw-user-agent-skills" description: "Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. Use when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Trigger keywords - nemoclaw agent skills, ai coding assistant, cursor, claude code, copilot." license: "Apache-2.0" --- + # NemoClaw Agent Skills for Your AI Coding Assistant -## References +NemoClaw ships agent skills that are generated directly from this documentation. +Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context. +This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately. + +Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation. +Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference. + +**Note:** + +If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root. +Open the `NemoClaw` directory in your coding assistant and the skills load automatically. +This page is for users who installed NemoClaw with the installer and do not have a local clone. + +## Get the Skills + +Fetch only the skills from the NemoClaw repository without downloading the full source tree. + +```bash +git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git +cd NemoClaw +git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md' +git checkout +``` + +Open the `NemoClaw` directory in your AI coding assistant. +The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance. + +You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects. +The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere. + +## Update the Skills + +The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree. +Run `git pull` after each NemoClaw release to pick up new and updated skills. + +## Available Skills + +The following user skills ship with NemoClaw. + +| Skill | Summary | +|-------|---------| +| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. | +| `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. | +| `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). | +| `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). | +| `nemoclaw-user-monitor-sandbox` | Check sandbox health, read logs, and trace agent behavior to diagnose problems. | +| `nemoclaw-user-deploy-remote` | Deploy NemoClaw to a remote GPU instance, set up the Telegram bridge, and review sandbox container hardening. | +| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. | +| `nemoclaw-user-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. | +| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. | + +## Example Questions and Triggered Skills + +After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language. +The assistant matches your question to the relevant skill and follows the guidance it contains. + +Examples of questions your assistant can answer with these skills: + +| Question | Skill triggered | +|----------|-----------------| +| "How do I install NemoClaw?" | `nemoclaw-user-get-started` | +| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` | +| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` | +| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` | +| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` | +| "What security controls can I configure?" | `nemoclaw-user-configure-security` | +| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` | +| "What CLI commands are available?" | `nemoclaw-user-reference` | + +You can also reference a skill directly by name if you know which one you need. + +## AI Coding Assistants that You Can Use with NemoClaw Skills + +The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). +The following table shows how each AI coding assistant can use the NemoClaw skills. -- **Load [references/agent-skills.md](references/agent-skills.md)** when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. +| Assistant | Skill discovery | +|-----------|----------------| +| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. | +| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. | +| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. | diff --git a/skills/nemoclaw-user-agent-skills/references/agent-skills.md b/skills/nemoclaw-user-agent-skills/references/agent-skills.md deleted file mode 100644 index cf2f6e95ea..0000000000 --- a/skills/nemoclaw-user-agent-skills/references/agent-skills.md +++ /dev/null @@ -1,83 +0,0 @@ -# NemoClaw Agent Skills for Your AI Coding Assistant - -NemoClaw ships agent skills that are generated directly from this documentation. -Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context. -This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately. - -Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation. -Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference. - -**Note:** - -If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root. -Open the `NemoClaw` directory in your coding assistant and the skills load automatically. -This page is for users who installed NemoClaw with the installer and do not have a local clone. - -## Get the Skills - -Fetch only the skills from the NemoClaw repository without downloading the full source tree. - -```console -$ git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git -$ cd NemoClaw -$ git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md' -$ git checkout -``` - -Open the `NemoClaw` directory in your AI coding assistant. -The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance. - -You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects. -The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere. - -## Update the Skills - -The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree. -Run `git pull` after each NemoClaw release to pick up new and updated skills. - -## Available Skills - -The following user skills ship with NemoClaw. - -| Skill | Summary | -|-------|---------| -| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. | -| `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. | -| `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). | -| `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). | -| `nemoclaw-user-monitor-sandbox` | Check sandbox health, read logs, and trace agent behavior to diagnose problems. | -| `nemoclaw-user-deploy-remote` | Deploy NemoClaw to a remote GPU instance, set up the Telegram bridge, and review sandbox container hardening. | -| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. | -| `nemoclaw-user-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. | -| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. | - -## Example Questions and Triggered Skills - -After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language. -The assistant matches your question to the relevant skill and follows the guidance it contains. - -Examples of questions your assistant can answer with these skills: - -| Question | Skill triggered | -|----------|-----------------| -| "How do I install NemoClaw?" | `nemoclaw-user-get-started` | -| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` | -| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` | -| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` | -| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` | -| "What security controls can I configure?" | `nemoclaw-user-configure-security` | -| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` | -| "What CLI commands are available?" | `nemoclaw-user-reference` | - -You can also reference a skill directly by name if you know which one you need. - -## AI Coding Assistants that You Can Use with NemoClaw Skills - -The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). -The following table shows how each AI coding assistant can use the NemoClaw skills. - -| Assistant | Skill discovery | -|-----------|----------------| -| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. | -| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. | -| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. | diff --git a/skills/nemoclaw-user-configure-inference/SKILL.md b/skills/nemoclaw-user-configure-inference/SKILL.md index 0a0d57e2ae..a097a63abc 100644 --- a/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/skills/nemoclaw-user-configure-inference/SKILL.md @@ -1,12 +1,9 @@ --- name: "nemoclaw-user-configure-inference" -description: "Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing." +description: "Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui." license: "Apache-2.0" --- - - - # Use a Local Inference Server ## Gotchas @@ -15,9 +12,14 @@ license: "Apache-2.0" ## Prerequisites -- NemoClaw installed. + + +- 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. @@ -28,13 +30,14 @@ OpenShell intercepts inference traffic and forwards it to the local endpoint you ## Ollama Ollama is the default local inference option. -The onboard wizard detects Ollama automatically when it is installed or running on the host. +The onboard wizard detects Ollama automatically when you have installed it or started it on the host. -If Ollama is installed but not running, NemoClaw starts it for you. +If you installed Ollama but have not started it, NemoClaw starts it for you. On macOS and Linux, the wizard can also offer to install Ollama when it is not present. When the host Ollama is below the minimum version NemoClaw expects for its starter models (currently `0.7.0`), the wizard surfaces an explicit **Upgrade Ollama** entry in the provider menu instead of silently reusing the older daemon, and the express setup path resolves to that entry. The wizard inspects both the CLI binary (`ollama --version`) and the locally running daemon (`/api/version` on `:11434`) so the upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon. -The gate skips Windows-host Ollama reached from WSL via `host.docker.internal`; the separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side. +The gate skips Windows-host Ollama reached from WSL through `host.docker.internal`. +The separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side. On macOS, the wizard runs the platform install or upgrade path with `brew upgrade ollama`. On Linux, the wizard runs the official `https://ollama.com/install.sh` path. Upgrades on Linux always take the sudo-driven system path because the sudo-free user-local fallback would leave the existing system daemon on `:11434` serving the stale binary. @@ -45,7 +48,7 @@ On WSL, the wizard can use, start, restart, or install Ollama on the Windows hos ### Linux Install Modes -On native Linux, the install path picks between a system install (under `/usr/local`, via the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`). +On native Linux, the install path picks between a system install (under `/usr/local`, using the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`). NemoClaw selects the mode automatically: - Running as root or with passwordless sudo (`sudo -n true` returns 0) selects the system install. @@ -56,21 +59,23 @@ NemoClaw selects the mode automatically: Override the detection with `NEMOCLAW_OLLAMA_INSTALL_MODE=system` or `NEMOCLAW_OLLAMA_INSTALL_MODE=user`. The user-local install replicates only the binary extraction step of the official installer. -It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` once. -It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so the daemon must be relaunched manually after a reboot. +It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` one time. +It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so you must relaunch the daemon manually after a reboot. NemoClaw also prints a one-line `PATH` hint if `${HOME}/.local/bin` is not already on your `PATH`; you can add `export PATH="${HOME}/.local/bin:$PATH"` to your shell profile to invoke `ollama` directly. Both modes rely on `zstd` for archive extraction. On Debian and Ubuntu, the system path uses `sudo apt-get` to install `zstd` automatically and explains the prompt before continuing. -The user-local path cannot bootstrap system packages without elevation, so if `zstd` is missing it prints per-distro install hints and exits — install `zstd` manually, then rerun onboarding. +The user-local path cannot bootstrap system packages without elevation. +If `zstd` is missing, it prints per-distro install hints and exits. +Install `zstd` manually, then rerun onboarding. Run the onboard wizard. -```console -$ nemoclaw onboard +```bash +nemoclaw onboard ``` Select **Local Ollama** from the provider list. -NemoClaw lists installed models or offers starter models if none are installed. +NemoClaw lists installed models or offers starter models if you have not installed any. On hosts where the larger starter models fit the currently available GPU memory, the starter list includes `qwen3.6:35b` and selects it by default. When another GPU workload is using most of the memory at onboard time, NemoClaw downgrades the menu to the largest model that still fits. It pulls the selected model, loads it into memory, and validates it before continuing. @@ -78,6 +83,7 @@ When Ollama reports a loaded-model context length, NemoClaw uses that value for If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show ` capabilities include `tools`. The validation also requires structured chat-completions tool calls. If the model leaks tool-call JSON as plain message text, onboarding stops so you can choose a model that returns tool calls in the expected response field. +If a host-side validation probe times out, NemoClaw retries the Ollama tool-call validation with a larger timeout before failing the setup. On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL. ### WSL with Windows-Host Ollama @@ -85,8 +91,8 @@ On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.i When NemoClaw runs inside WSL, the provider menu can include Windows-host Ollama actions: - Use Ollama on Windows host when the Windows daemon is already reachable. -- Restart Ollama on Windows host when the daemon is installed but only bound to Windows loopback. -- Start Ollama on Windows host when Ollama is installed but not running. +- Restart Ollama on Windows host when you installed the daemon but bound it only to Windows loopback. +- Start Ollama on Windows host when you installed Ollama but have not started it. - Install Ollama on Windows host when Windows does not have Ollama installed. The install and restart paths set `OLLAMA_HOST=0.0.0.0:11434` on the Windows side so Docker and WSL can reach the daemon through `host.docker.internal`. @@ -96,6 +102,11 @@ If the HTTP endpoint is not reachable yet, NemoClaw also checks for the Windows If the daemon does not become reachable, onboarding prints PowerShell commands you can run to inspect the Windows-side process and port state. Use one Ollama instance on port `11434` at a time. If both WSL and Windows-host Ollama are running, pick the intended menu entry during onboarding so NemoClaw validates and pulls models against the right daemon. +Windows-host Ollama requires Docker Desktop WSL integration because the sandbox reaches the Windows daemon through Docker Desktop's WSL routing path. +If NemoClaw detects native Docker Engine inside WSL, the provider menu labels Windows-host Ollama actions as requiring Docker Desktop integration. +Selecting one of those actions in the unsupported native Docker topology exits early with a remediation message instead of trying to start or install Ollama on Windows. + + **Warning:** Ollama is convenient for local chat, but some model/template combinations can @@ -103,13 +114,13 @@ return tool calls as plain text under realistic agent load. If the TUI shows raw JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a tool, switch to vLLM with `--enable-auto-tool-choice` and the correct `--tool-call-parser`. See [Tool-Calling Reliability](references/tool-calling-reliability.md). + ### Authenticated Reverse Proxy On non-WSL hosts, NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated reverse proxy on `0.0.0.0:11435`. The native install/start paths also reset NemoClaw-managed systemd launches to the loopback binding. -Containers and other hosts on the local network reach Ollama only through the -proxy, which validates a Bearer token before forwarding requests. +Containers and other hosts on the local network reach Ollama only through the proxy, which validates a Bearer token before forwarding requests. On that native path, NemoClaw never exposes Ollama without authentication. WSL Ollama paths do not use this proxy. @@ -129,22 +140,19 @@ For non-WSL Ollama setups, the onboard wizard manages the proxy automatically: On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge. When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like: -```console -$ sudo ufw allow from to any port 11435 proto tcp -$ nemoclaw onboard +```bash +sudo ufw allow from to any port 11435 proto tcp +nemoclaw onboard ``` If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check. -The sandbox provider is configured to use proxy port `11435` with the generated -token as its `OPENAI_API_KEY` credential. -OpenShell's L7 proxy injects the token at egress, so the agent inside the -sandbox never sees the token directly. +NemoClaw configures the sandbox provider to use proxy port `11435` with the generated token as its `OPENAI_API_KEY` credential. +OpenShell's L7 proxy injects the token at egress, so the agent inside the sandbox never sees the token directly. All proxy endpoints require the Bearer token, including `GET /api/tags`. -Internal health and reachability checks run via the proxy treat any HTTP -response (including `401`) as proof the proxy is alive — they only fail -when nothing answers at all. +Internal health and reachability checks run through the proxy treat any HTTP response, including `401`, as proof the proxy is alive. +They fail only when nothing answers at all. If Ollama is already running on a non-loopback address when you start onboard, the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network @@ -156,126 +164,76 @@ When you switch away from Ollama, stop host services, or destroy an Ollama-backe The cleanup sends `keep_alive: 0` for each model reported by Ollama and runs on a best-effort basis, so shutdown continues if Ollama is already stopped. This does not delete downloaded model files. -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup. +### Non-Interactive Setup -## OpenAI-Compatible Server - -This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. -For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. -This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions. -To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard. - -Start your model server. -The examples below use vLLM, but any OpenAI-compatible server works. - -```console -$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 +```bash +NEMOCLAW_PROVIDER=ollama \ + NEMOCLAW_MODEL=qwen3.5:9b \ + nemoclaw onboard --non-interactive --yes ``` -Run the onboard wizard. +If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. +If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. +Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. -```console -$ nemoclaw onboard -``` +`--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt. +Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download. +Onboard exits otherwise because it cannot prompt. +Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading. -When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. -Enter the base URL of your local server, for example `http://localhost:8000/v1`. +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `ollama`. | +| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | +| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. | -The wizard prompts for an API key. -If your server does not require authentication, enter any non-empty string (for example, `dummy`). +## Compatible Local Servers -NemoClaw validates the endpoint by sending a test inference request before continuing. -The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider. -If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires. -If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget. -Route, configuration, and authentication failures still fail immediately. +Use **Other OpenAI-compatible endpoint** for vLLM, TensorRT-LLM, llama.cpp, LocalAI, NIM, SGLang, or another server that implements `/v1/chat/completions`. +For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default because some local backends accept `/v1/responses` but drop system prompts or tool definitions. +Set `NEMOCLAW_PREFERRED_API=openai-responses` only after you have verified that the backend streams the events OpenClaw requires. -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup, Selecting the API Path. +For the full compatible-endpoint prompt flow, non-interactive variables, API-path controls, managed vLLM profiles, NIM setup, and timeout settings, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers). -## Anthropic-Compatible Server +## Managed vLLM and NIM -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. +NemoClaw can use an already-running vLLM server on `localhost:8000`, start managed vLLM on supported NVIDIA GPU hosts, or manage a local NIM container when `NEMOCLAW_EXPERIMENTAL=1` is set. +Managed vLLM records the model returned by `/v1/models` and uses runtime metadata such as `max_model_len` when available. +NIM uses the same chat-completions API path restriction as vLLM. -## vLLM +For registry slugs, Hugging Face token requirements, NGC login behavior, and non-interactive examples, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers). -When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. -On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. +## Verify the Configuration -For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. +After onboarding completes, confirm the active provider and model. -```console -$ nemoclaw onboard +```bash +nemoclaw status ``` -If vLLM is already running, NemoClaw detects the running model and validates the endpoint. -If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. -Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. -NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, and prints progress markers while the model loads. -The first run can take 10 to 30 minutes. -Later runs reuse the cached image and model weights. - -Managed vLLM uses these profiles: - -| Host profile | Default model | -|---|---| -| DGX Spark | `Qwen/Qwen3.6-27B-FP8` | -| DGX Station | `Qwen/Qwen3.6-27B-FP8` | -| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | - -**Note:** +The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. +For Local Ollama, status also checks the authenticated proxy when a proxy token is available. +If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use. -NemoClaw forces the `chat/completions` API path for vLLM. -The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. - -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup, Override the Managed-vLLM Model. - -## NVIDIA NIM (Experimental) +## Switch Models at Runtime -NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. +You can change the model without re-running onboard. +Refer to [Switch Inference Models](references/switch-inference-providers.md) for the full procedure. -Set the experimental flag and run onboard. +For compatible endpoints, the command is: -```console -$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +```bash +nemoclaw inference set --provider compatible-endpoint --model ``` -Select **Local NVIDIA NIM [experimental]** from the provider list. -NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. -On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. - -NIM container images are hosted on `nvcr.io` and require NGC registry authentication before `docker pull` succeeds. -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 once 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 the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines. - -**Note:** - -NIM uses vLLM internally. -The same `chat/completions` API path restriction applies. - -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup. - -## Timeout Configuration - -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. - -## Verify the Configuration - -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. - -## Switch Models at Runtime - -Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. +If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. ## References - **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox. - **Load [references/set-up-sub-agent.md](references/set-up-sub-agent.md)** when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model. -- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when vLLM with a tool-call parser is recommended, and how to repoint NemoClaw to a parser-aware local endpoint. - **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding. -- **Load [references/use-local-inference-details.md](references/use-local-inference-details.md)** when you need detailed steps for Non-Interactive Setup, Selecting the API Path, Anthropic-Compatible Server, and related details. +- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when to use vLLM with a tool-call parser, and how to repoint NemoClaw to a parser-aware local endpoint. ## Related Skills diff --git a/skills/nemoclaw-user-configure-inference/references/inference-options.md b/skills/nemoclaw-user-configure-inference/references/inference-options.md index 5242cff46c..c54a6d9032 100644 --- a/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -1,10 +1,20 @@ - - # NemoClaw Inference Options +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw supports multiple inference providers. -During onboarding, the `nemoclaw onboard` wizard presents a numbered list of providers to choose from. -Your selection determines where the agent's inference traffic is routed. +During onboarding, the NemoClaw onboarding wizard presents a numbered list of providers to choose from. +Your selection determines where NemoClaw routes the agent's inference traffic. + + +For OpenClaw onboarding, use `nemoclaw onboard`. +The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent. + + + +For Hermes onboarding, use `nemoclaw onboard`. +The provider flow is the same, with the Hermes Provider route available for Hermes Agent. + ## How Inference Routing Works @@ -37,13 +47,13 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l The onboard wizard presents the following provider options by default. The first six are always available. -Ollama appears when it is installed or running on the host. +Ollama appears when you have installed or started it on the host. Local vLLM appears when NemoClaw detects a running vLLM server. The managed install/start vLLM entry appears by default on DGX Spark and DGX Station, and appears on generic Linux NVIDIA GPU hosts after opt-in. | 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, 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_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` | @@ -57,7 +67,7 @@ The managed install/start vLLM entry appears by default on DGX Spark and DGX Sta NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported deployment surface, so two onboarding options can route to Nemotron. -| Where Nemotron is hosted | Onboard wizard option | Why | +| Nemotron Host | Onboard Wizard Option | Why | |---|---|---| | `build.nvidia.com` (NVIDIA-hosted) | **Option 1: NVIDIA Endpoints** | NemoClaw sets the base URL to `https://integrate.api.nvidia.com/v1` for you and validates the model against the build catalog. | | Self-hosted NIM container | **Option 3: Other OpenAI-compatible endpoint** | NIM exposes an OpenAI-compatible `/v1/chat/completions` route. Point the base URL at your NIM service and enter the Nemotron model ID. | @@ -74,14 +84,53 @@ When you select it, NemoClaw starts the router proxy on the host, waits for its The sandbox does not call the router port directly. The router model pool lives in `nemoclaw-blueprint/router/pool-config.yaml`. +Edit that file to define which models the router can choose from. The default pool routes between NVIDIA-hosted Nemotron models and uses the `tolerance` value to choose the lowest-cost model whose predicted quality stays within the configured threshold. + +```yaml +routing: + method: prefill + checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt + tolerance: 0.20 + encoder: Qwen/Qwen3.5-0.8B + +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" + + - name: super + litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3" + cost_per_m_input_tokens: 0.10 + api_base: "https://inference-api.nvidia.com" +``` + +The `tolerance` parameter controls the accuracy-cost tradeoff. + +| Value | Behavior | +|-------|----------| +| `0.0` | Always pick the most accurate model. | +| `0.20` | Allow up to 20 percentage points below the best for a cheaper model (default). | +| `1.0` | Always pick the cheapest model. | + +The router runs on the host, not inside the sandbox. + +```text +Sandbox (agent) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API + └── PrefillRouter selects model +``` + +Credentials flow through the OpenShell provider system. +The sandbox never sees raw API keys. + To use the router in scripted setup, set: -```console -$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +```bash +NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive ``` -### Host Python requirement +### Host Python Requirement The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding. NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of: @@ -94,18 +143,19 @@ This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`: -```console -$ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard +```bash +NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard ``` The pin is strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`. -Relative command names such as `python3.12` are rejected; use `command -v python3.12` to find the absolute path. +NemoClaw rejects relative command names such as `python3.12`. +Use `command -v python3.12` to find the absolute path. If `python -m venv` itself fails for a probe-clean interpreter (for example, a corrupt ensurepip seed), NemoClaw retries with the next healthy candidate when no pin is set; with a pin set, the failure stops onboarding so you can fix or repoint the pinned python. ## Caveated Local Options -The following local inference options are caveated. +The following local inference options have caveats. Local NIM and generic Linux managed vLLM install/start require `NEMOCLAW_EXPERIMENTAL=1`; DGX Spark and DGX Station managed vLLM entries appear by default. An already-running vLLM server appears directly in the onboarding selection list. @@ -120,23 +170,262 @@ 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. -Transient upstream validation failures are retried before the wizard reports a provider failure. +The wizard retries transient upstream validation failures before it reports a provider failure. The `nvapi-` prefix check applies only to `NVIDIA_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 | |---|---| | OpenAI | Tries `/responses` first, then `/chat/completions`. | -| NVIDIA Endpoints | Validates via `/v1/chat/completions` only; the `/v1/responses` probe is skipped because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). | -| Google Gemini | Validates via Gemini's OpenAI-compatible chat-completions path only; the `/v1/responses` probe is skipped because Gemini does not support the Responses API. | +| NVIDIA Endpoints | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). | +| Google Gemini | Validates through Gemini's OpenAI-compatible chat-completions path only; NemoClaw skips the `/v1/responses` probe because Gemini does not support the Responses API. | | Other OpenAI-compatible endpoint | Tries `/v1/responses` first with a tool-calling probe; falls back to `/v1/chat/completions`. Selected runtime API defaults to `/v1/chat/completions`; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. | | Anthropic-compatible | Tries `/v1/messages`. | | NVIDIA Endpoints (manual model entry) | Validates the model name against the catalog API. | | Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe tries `/v1/responses` first then falls back to `/v1/chat/completions`; the selected runtime API defaults to `/v1/chat/completions`. Set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. | -| Local NVIDIA NIM | Validates via `/v1/chat/completions` only; the `/v1/responses` probe is skipped (same as NVIDIA Endpoints). | +| Local NVIDIA NIM | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe (same as NVIDIA Endpoints). | + +## Setup Details for Local and Compatible Providers + +The sections below collect the detailed setup prompts and environment variables for local and compatible inference providers. +Use them when the quickstart or local inference guide points you here for exact command shapes. + +## OpenAI-Compatible Server + +This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. +For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. +This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions. +To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard. + +Start your model server. +The examples below use vLLM, but any OpenAI-compatible server works. + +```bash +vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 +``` + +Run the onboard wizard. + +```bash +nemoclaw onboard +``` + +When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. +Enter the base URL of your local server, for example `http://localhost:8000/v1`. + +The wizard prompts for an API key. +If your server does not require authentication, enter any non-empty string (for example, `dummy`). + +NemoClaw validates the endpoint by sending a test inference request before continuing. +The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider. +If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires. +If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget. +Route, configuration, and authentication failures still fail immediately. + +### Non-Interactive Setup + +Set the following environment variables for scripted or CI/CD deployments. + +```bash +NEMOCLAW_PROVIDER=custom \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ + NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ + COMPATIBLE_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `custom` for an OpenAI-compatible endpoint. | +| `NEMOCLAW_ENDPOINT_URL` | Base URL of the local server. | +| `NEMOCLAW_MODEL` | Model ID as reported by the server. | +| `COMPATIBLE_API_KEY` | API key for the endpoint. Use any non-empty value if authentication is not required. | + +### Selecting the API Path + +For the compatible-endpoint provider, `/v1/chat/completions` is the default. +NemoClaw tests streaming events during onboarding and uses chat completions +without probing the Responses API. + +To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: + +```bash +NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +``` + +The wizard then probes `/v1/responses` and only selects it when streaming +support is complete. +If the probe fails, the wizard falls back to `/v1/chat/completions` +automatically. +You can use this variable in both interactive and non-interactive mode. + +| Variable | Values | Default | +|---|---|---| +| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | + +If you already onboarded and the sandbox is failing at runtime, re-run `nemoclaw onboard` to re-probe the endpoint and bake the correct API path +into the image. +Refer to [Switch Inference Models](switch-inference-providers.md) for more information. + +## Anthropic-Compatible Server + +If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. + +```bash +nemoclaw onboard +``` + +For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. + +```bash +NEMOCLAW_PROVIDER=anthropicCompatible \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ + NEMOCLAW_MODEL=my-model \ + COMPATIBLE_ANTHROPIC_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +## vLLM + +When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. +On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. + +For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. + +If vLLM is already running, NemoClaw detects the running model and validates the endpoint. +When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself. +If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. +Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. +NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready. +If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. +If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting. +The first run can take 10 to 30 minutes. +Later runs reuse the cached image and model weights. + +Managed vLLM uses these profiles: + +| Host profile | Default model | +|---|---| +| DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` | +| DGX Station | `deepseek-ai/DeepSeek-V4-Flash` | +| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | + +**Note:** + +NemoClaw forces the `chat/completions` API path for vLLM. +The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. + +### Non-Interactive Setup + +Use an already-running vLLM server: + +```bash +NEMOCLAW_PROVIDER=vllm \ + nemoclaw onboard --non-interactive +``` + +Install or start managed vLLM when NemoClaw detects a supported profile. +On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts. + +```bash +NEMOCLAW_PROVIDER=install-vllm \ + nemoclaw onboard --non-interactive +``` + +NemoClaw records the model returned by vLLM's `/v1/models` endpoint. +Start vLLM with the model you want before onboarding if you manage the server yourself. + +### Override the Managed-vLLM Model + +Managed vLLM serves the profile default unless you select a different registry entry. +Export `NEMOCLAW_VLLM_MODEL=` before invoking the installer to choose a different model from the registry. +NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`. +Recognized slugs are: + +| Slug | Hugging Face model | Notes | +|---|---|---| +| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Default on the DGX Station profile | +| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Supported override | +| `qwen3.6-35b-a3b-nvfp4` | `nvidia/Qwen3.6-35B-A3B-NVFP4` | Default on the DGX Spark profile | +| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile | +| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance | + +The slug is case-insensitive; the full Hugging Face id is also accepted. +An unrecognized value fails fast with a list of valid slugs. + +Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container: + +```bash +export HF_TOKEN= +NEMOCLAW_PROVIDER=install-vllm \ + NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ + nemoclaw onboard --non-interactive +``` + +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. + +## NVIDIA NIM (Experimental) + +NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. + +Set the experimental flag and run onboard. + +```bash +NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +``` + +Select **Local NVIDIA NIM [experimental]** from the provider list. +NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. +On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. + +NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication. +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 the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines. + +**Note:** + +NIM uses vLLM internally. +The same `chat/completions` API path restriction applies. + +## Timeout Configuration + +Local inference requests use a default timeout of 180 seconds. +Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup. + +To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: + +```bash +export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +nemoclaw onboard +``` + +The value is in seconds. +NemoClaw bakes this setting into the sandbox at build time. +Changing it after onboarding requires re-running `nemoclaw onboard`. + +`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe. +During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure. +NemoClaw also retries Docker runtime detection with a longer `docker info` timeout before it chooses the local inference route. +The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds. +On hosts where the sandbox image takes minutes to build or upload, raise both settings together. +Examples include large quantized models, DGX Station first runs, and remote VMs over a slow link. + +```bash +export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 +nemoclaw onboard +``` + +If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). ## Next Steps - [Use a Local Inference Server](../SKILL.md) for Ollama, vLLM, NIM, and compatible-endpoint setup details. + - [Tool-Calling Reliability](tool-calling-reliability.md) for deciding when Ollama is enough and when vLLM with a parser is safer. + - [Switch Inference Models](switch-inference-providers.md) for changing the model at runtime without re-onboarding. diff --git a/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md b/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md index 148eaf0e7e..48cf9b38c4 100644 --- a/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md +++ b/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md @@ -1,5 +1,3 @@ - - # Set Up Task-Specific Sub-Agents OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents). @@ -37,17 +35,17 @@ It keeps the primary `main` agent on the normal NemoClaw inference route and add | Sub-agent model | `nvidia-omni/private/nvidia/nemotron-3-nano-omni-reasoning-30b-a3b` | | Delegation tool | `sessions_spawn` | -Omni is used as the specialist model for image tasks. +The sub-agent uses Omni as the specialist model for image tasks. The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate. ## 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. -```console -$ 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 +```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 ``` Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. @@ -56,13 +54,13 @@ 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. -```console -$ 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 +```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 ``` Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change. @@ -77,10 +75,10 @@ For the Omni example: ``` Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`. -After uploading the auth profile, make sure the sub-agent directory is owned by the sandbox user: +After uploading the auth profile, make sure the sandbox user owns the sub-agent directory: -```console -$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator +```bash +docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator ``` ## Allow Auxiliary Provider Egress diff --git a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md index c5a623c42e..92089e996c 100644 --- a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md +++ b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -1,9 +1,9 @@ - - # Switch Inference Models at Runtime +import { AgentOnly } from "../_components/AgentGuide"; + Change the active inference model while the sandbox is running. -No restart is required. +You do not need to restart the sandbox. ## Prerequisites @@ -12,100 +12,122 @@ No restart is required. ## Switch to a Different Model + Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace. + + +Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. +The command updates the OpenShell inference route and synchronizes the running agent config. For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes. +Pass `--sandbox ` when you do not want to use the default registered sandbox. +Under `nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. + + Pass `--sandbox ` when you do not want to use the default registered sandbox. -Under `nemohermes`, pass `--sandbox ` when more than one Hermes sandbox is registered. + ### NVIDIA Endpoints -```console -$ nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +```bash +nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` ### OpenAI -```console -$ nemoclaw inference set --provider openai-api --model gpt-5.4 +```bash +nemoclaw inference set --provider openai-api --model gpt-5.4 ``` ### Anthropic -```console -$ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 +```bash +nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 ``` ### Google Gemini -```console -$ nemoclaw inference set --provider gemini-api --model gemini-2.5-flash +```bash +nemoclaw inference set --provider gemini-api --model gemini-2.5-flash ``` ### Compatible Endpoints If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: -```console -$ nemoclaw inference set --provider compatible-endpoint --model +```bash +nemoclaw inference set --provider compatible-endpoint --model ``` -```console -$ nemoclaw inference set --provider compatible-anthropic-endpoint --model +```bash +nemoclaw inference set --provider compatible-anthropic-endpoint --model ``` + + ### Hermes Provider For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered Hermes Provider route: -```console -$ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini +```bash +nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini ``` + + #### Switching from Responses API to Chat Completions -If onboarding selected `/v1/responses` but the agent fails at runtime (for -example, because the backend does not emit the streaming events OpenClaw -requires), re-run onboarding so the wizard re-probes the endpoint and bakes -the correct API path into the image: +If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. +This can happen when the backend does not emit the streaming events OpenClaw requires. -```console -$ nemoclaw onboard +```bash +nemoclaw onboard ``` Select the same provider and endpoint again. -The updated streaming probe will detect incomplete `/v1/responses` support -and select `/v1/chat/completions` automatically. +The updated streaming probe detects incomplete `/v1/responses` support and selects `/v1/chat/completions` automatically. -For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by -default, so no env var is required to keep the safe path. -To opt in to `/v1/responses` for a backend you have verified end to end, set -`NEMOCLAW_PREFERRED_API` before onboarding: +For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by default, so you do not need an environment variable to keep the safe path. +To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding: -```console -$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +```bash +NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard ``` **Note:** -`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but -does not update the Dockerfile ARG baked into the image. -If you recreate the sandbox without the override env var, the image reverts to -the original API path. +`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image. +If you recreate the sandbox without the override environment variable, the image reverts to the original API path. A fresh `nemoclaw onboard` is the reliable fix because it updates both the session and the baked image. ## Cross-Provider Switching + Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`. The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config. +If the in-sandbox config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint. +Run the rebuild before relying on the running agent if the warning says the image config could not be patched. -```console -$ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +```bash +nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify ``` + + +Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`. +The command updates both the gateway route and `/sandbox/.hermes/config.yaml`. +If the Hermes config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint. +Run the rebuild before relying on the running agent if the warning says the image config could not be patched. + +```bash +nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +``` + + + Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential. ## Tune Model Metadata @@ -122,27 +144,40 @@ To change these values, set the corresponding environment variables before runni | `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` | | `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | Go-style duration (`30m`, `1h`, `0m` to disable) | `unset` (OpenClaw default) | -Invalid values are ignored, and the default bakes into the image. +NemoClaw ignores invalid values and bakes the default into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. +For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. -```console -$ export NEMOCLAW_CONTEXT_WINDOW=65536 -$ export NEMOCLAW_MAX_TOKENS=8192 -$ export NEMOCLAW_REASONING=true -$ export NEMOCLAW_INFERENCE_INPUTS=text,image -$ export NEMOCLAW_AGENT_TIMEOUT=1800 -$ export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m -$ nemoclaw onboard -``` - -`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into -`agents.defaults.timeoutSeconds`. Increase it for slow local inference (for -example, CPU-only Ollama or vLLM on modest hardware). NemoClaw writes this -value into `openclaw.json` during onboarding. The default sandbox may keep that -file writable for agent state, but direct in-sandbox edits are not the supported -or durable way to change NemoClaw-managed defaults. Rebuild the sandbox via -`nemoclaw onboard` to apply a new value. +```bash +export NEMOCLAW_CONTEXT_WINDOW=65536 +export NEMOCLAW_MAX_TOKENS=8192 +export NEMOCLAW_REASONING=true +export NEMOCLAW_INFERENCE_INPUTS=text,image +export NEMOCLAW_AGENT_TIMEOUT=1800 +export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m +nemoclaw onboard +``` + + + +`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`. +Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware. +NemoClaw writes this value into `openclaw.json` during onboarding. +The default sandbox can keep that file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. +Rebuild the sandbox with `nemoclaw onboard` to apply a new value. + + + + +`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into the Hermes sandbox image. +Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware. +Direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. +Rebuild the sandbox with `nemoclaw onboard` to apply a new value. + + + + `NEMOCLAW_AGENT_HEARTBEAT_EVERY` sets `agents.defaults.heartbeat.every`. This controls OpenClaw's periodic main-session agent turn. @@ -151,15 +186,22 @@ The OpenClaw default is 30 minutes (1 hour for Anthropic OAuth / Claude CLI reus Tune the cadence with a duration string like `5m` or `2h`, or set `0m` to disable the periodic turns entirely. Disabling also drops `HEARTBEAT.md` from normal-run bootstrap context per upstream behavior, so the model no longer sees heartbeat-only instructions. NemoClaw writes this value into `openclaw.json` during onboarding. -The in-sandbox `openclaw config set` command is not the supported path for -NemoClaw-managed build-time defaults, and direct file edits are overwritten by a -rebuild. Rebuild the sandbox via `nemoclaw onboard --resume` to apply a new value. +The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and a rebuild overwrites direct file edits. +Rebuild the sandbox with `nemoclaw onboard --resume` to apply a new value. + + + + +Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. +Rebuild the sandbox with `nemoclaw onboard --resume` to apply build-time inference metadata changes. + + These variables are build-time settings. If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image: -```console -$ nemoclaw onboard --resume --recreate-sandbox +```bash +nemoclaw onboard --resume --recreate-sandbox ``` ## Verify the Active Model @@ -188,20 +230,33 @@ Run `nemoclaw onboard` to configure one. Run the status command when you also need sandbox, service, and messaging health: -```console -$ nemoclaw status +```bash +nemoclaw status ``` The status output includes the active provider, model, and endpoint with the rest of the sandbox state. ## Notes + + - The host keeps provider credentials. - The sandbox continues to use `inference.local`. - `nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash. - Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. - Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. + + + +- The host keeps provider credentials. +- The sandbox continues to use `inference.local`. +- `nemoclaw inference set` patches the selected running Hermes sandbox config and recomputes its config hash. +- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. +- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. + + + ## Related Topics - [Inference Options](inference-options.md) for the full list of providers available during onboarding. diff --git a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md index 01f2c36115..d415ce4dda 100644 --- a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md +++ b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md @@ -1,11 +1,7 @@ - - # Tool-Calling Reliability for Local Inference -Local inference is useful for privacy, cost control, and offline development, but -tool-calling agents place stricter demands on the model server than simple chat. -The model server must return structured `tool_calls`, not a JSON-looking string -inside normal assistant text. +Local inference is useful for privacy, cost control, and offline development, but tool-calling agents place stricter demands on the model server than simple chat. +The model server must return structured `tool_calls`, not a JSON-looking string inside normal assistant text. Use this page when the TUI shows raw JSON such as: @@ -13,8 +9,7 @@ Use this page when the TUI shows raw JSON such as: {"arguments":{"query":"robotics"},"name":"memory_search"} ``` -If that appears as text in the assistant reply, OpenClaw cannot dispatch the -tool because the inference response did not include a structured tool call. +If that appears as text in the assistant reply, OpenClaw cannot dispatch the tool because the inference response did not include a structured tool call. ## Quick Choice Guide @@ -28,9 +23,8 @@ tool because the inference response did not include a structured tool call. | Multi-turn tool dispatch | Risky | Yes | Ollama can work well for lightweight local chat and some simple tool surfaces. -For OpenClaw-style agent loops with multiple tools, long instructions, or -multi-turn dispatch, use a server that exposes OpenAI-compatible -`/v1/chat/completions` with a tool-call parser. vLLM is the common local choice. +For OpenClaw-style agent loops with multiple tools, long instructions, or multi-turn dispatch, use a server that exposes OpenAI-compatible `/v1/chat/completions` with a tool-call parser. +vLLM is the common local choice. ## Symptom @@ -41,20 +35,17 @@ The common failure mode is: - The gateway treats the response as normal text. - No tool runs, and the user sees raw JSON in the TUI. -This is different from a network or policy block. `nemoclaw status`, -`nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while -tool dispatch still fails inside the conversation. +This is different from a network or policy block. +`nemoclaw status`, `nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation. ## Recommended Fix -For persistent NemoClaw use, start vLLM with auto tool choice and the parser that -matches your model family, then rerun onboarding and select **Local vLLM -[experimental]** or **Other OpenAI-compatible endpoint**. +For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**. For Hermes 3 style models, a known-good vLLM command shape is: -```console -$ vllm serve /models/Hermes-3-Llama-3.1-8B \ +```bash +vllm serve /models/Hermes-3-Llama-3.1-8B \ --served-model-name hermes-3-llama-3.1-8b \ --enable-auto-tool-choice \ --tool-call-parser hermes \ @@ -93,22 +84,20 @@ services: Then onboard against that endpoint: -```console -$ NEMOCLAW_PROVIDER=custom \ +```bash +NEMOCLAW_PROVIDER=custom \ NEMOCLAW_ENDPOINT_URL=http://localhost:8002/v1 \ NEMOCLAW_MODEL=hermes-3-llama-3.1-8b \ COMPATIBLE_API_KEY=$VLLM_API_KEY \ nemoclaw onboard --non-interactive ``` -If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any -non-empty placeholder, such as `dummy`. +If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any non-empty placeholder, such as `dummy`. ## Advanced Temporary Repointing -NemoClaw-managed sandboxes normally block direct `openclaw config set` writes -inside the sandbox because those edits do not survive rebuilds. Prefer rerunning -`nemoclaw onboard` for a persistent provider change. +NemoClaw-managed sandboxes normally block direct `openclaw config set` writes inside the sandbox because those edits do not survive rebuilds. +Prefer rerunning `nemoclaw onboard` for a persistent provider change. If you are intentionally testing a mutable OpenClaw config, prepare a batch file like this: @@ -134,15 +123,13 @@ like this: } ``` -Apply it only in environments where OpenClaw config writes are allowed: +Apply it only in environments where OpenClaw allows config writes: -```console -$ openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json +```bash +openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json ``` -After testing, persist the working provider through `nemoclaw onboard` so the -sandbox image, OpenShell inference route, and host-managed credentials stay in -sync. +After testing, persist the working provider through `nemoclaw onboard` so the sandbox image, OpenShell inference route, and host-managed credentials stay in sync. ## Verify the Fix @@ -150,12 +137,9 @@ After switching to vLLM, ask for an action that should use a tool. Good signs: - The TUI does not show JSON blobs as assistant text. - The gateway log shows tool dispatch and a follow-up answer. -- `nemoclaw status` reports the local vLLM or compatible endpoint as the - active provider. +- `nemoclaw status` reports the local vLLM or compatible endpoint as the active provider. -If JSON still appears as text, confirm that vLLM was started with both -`--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your -model. +If JSON still appears as text, confirm that you started vLLM with both `--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your model. ## Next Steps diff --git a/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md b/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md deleted file mode 100644 index fab5e58f2b..0000000000 --- a/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md +++ /dev/null @@ -1,151 +0,0 @@ - - -# Use a Local Inference Server: Details - -## Non-Interactive Setup - -```console -$ NEMOCLAW_PROVIDER=ollama \ - NEMOCLAW_MODEL=qwen2.5:14b \ - nemoclaw onboard --non-interactive --yes -``` - -If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. -If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. -Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. - -`--yes` (or `NEMOCLAW_YES=1`) authorises the Ollama model download without an interactive confirmation prompt. -Under `--non-interactive`, `--yes` (or `NEMOCLAW_YES=1`) is required to authorise the download — onboard exits otherwise, since it cannot prompt. -Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading. - -| Variable | Purpose | -|---|---| -| `NEMOCLAW_PROVIDER` | Set to `ollama`. | -| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | -| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. | - -### Selecting the API Path - -For the compatible-endpoint provider, `/v1/chat/completions` is the default. -NemoClaw tests streaming events during onboarding and uses chat completions -without probing the Responses API. - -To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: - -```console -$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard -``` - -The wizard then probes `/v1/responses` and only selects it when streaming -support is complete. -If the probe fails, the wizard falls back to `/v1/chat/completions` -automatically. -You can use this variable in both interactive and non-interactive mode. - -| Variable | Values | Default | -|---|---|---| -| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | - -If you already onboarded and the sandbox is failing at runtime, re-run -`nemoclaw onboard` to re-probe the endpoint and bake the correct API path -into the image. -Refer to [Switch Inference Models](switch-inference-providers.md) for details. - -## Anthropic-Compatible Server - -If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. - -```console -$ nemoclaw onboard -``` - -For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. - -```console -$ NEMOCLAW_PROVIDER=anthropicCompatible \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ - NEMOCLAW_MODEL=my-model \ - COMPATIBLE_ANTHROPIC_API_KEY=dummy \ - nemoclaw onboard --non-interactive -``` - -### Override the Managed-vLLM Model - -Managed vLLM serves the profile default unless you select a different registry entry. -Export `NEMOCLAW_VLLM_MODEL=` before invoking the installer to choose a different model from the registry. -NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`. -Recognised slugs: - -| Slug | Hugging Face model | Notes | -|---|---|---| -| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on DGX Spark and DGX Station profiles | -| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile | -| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance | - -The slug is case-insensitive; the full Hugging Face id is also accepted. -An unrecognised value fails fast with a list of valid slugs. - -Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container: - -```console -$ export HF_TOKEN= -$ NEMOCLAW_PROVIDER=install-vllm \ - NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ - nemoclaw onboard --non-interactive -``` - -`HUGGING_FACE_HUB_TOKEN` is accepted 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. - -## Timeout Configuration - -Local inference requests use a default timeout of 180 seconds. -Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup. - -To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: - -```console -$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -$ nemoclaw onboard -``` - -The value is in seconds. -This setting is baked into the sandbox at build time. -Changing it after onboarding requires re-running `nemoclaw onboard`. - -`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe. -The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds. -On hosts where the sandbox image takes minutes to build or upload — large quantised models, DGX Station first runs, or remote VMs over a slow link — raise both together: - -```console -$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -$ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -$ nemoclaw onboard -``` - -If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). - -## Verify the Configuration - -After onboarding completes, confirm the active provider and model. - -```console -$ nemoclaw status -``` - -The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. -For Local Ollama, status also checks the authenticated proxy when a proxy token is available. -If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use. - -## Switch Models at Runtime - -You can change the model without re-running onboard. -Refer to [Switch Inference Models](switch-inference-providers.md) for the full procedure. - -For compatible endpoints, the command is: - -```console -$ nemoclaw inference set --provider compatible-endpoint --model -``` - -If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. diff --git a/skills/nemoclaw-user-configure-security/SKILL.md b/skills/nemoclaw-user-configure-security/SKILL.md index 36df08415f..865e4aa6d8 100644 --- a/skills/nemoclaw-user-configure-security/SKILL.md +++ b/skills/nemoclaw-user-configure-security/SKILL.md @@ -4,13 +4,10 @@ description: "Presents a risk framework for every configurable security control license: "Apache-2.0" --- - - - -# NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles +# NemoClaw User Configure Security ## References - **Load [references/best-practices.md](references/best-practices.md)** when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs. Presents a risk framework for every configurable security control in NemoClaw. -- **Load [references/openclaw-controls.md](references/openclaw-controls.md)** when reviewing the security boundary between NemoClaw and OpenClaw or assessing what NemoClaw does not cover. Lists OpenClaw security controls that operate independently of NemoClaw, including prompt injection detection, tool access control, rate limiting, environment variable policy, audit framework, supply chain scanning, messaging access policy, context visibility, and safe regex. - **Load [references/credential-storage.md](references/credential-storage.md)** when reviewing how credentials are handled, locating a stored credential, or assessing the storage threat model. Covers where NemoClaw stores provider credentials, why nothing is persisted to host disk, and how the OpenShell gateway acts as the single system of record. +- **Load [references/openclaw-controls.md](references/openclaw-controls.md)** when reviewing the security boundary between NemoClaw and OpenClaw or assessing what NemoClaw does not cover. Lists OpenClaw security controls that operate independently of NemoClaw, including prompt injection detection, tool access control, rate limiting, environment variable policy, audit framework, supply chain scanning, messaging access policy, context visibility, and safe regex. diff --git a/skills/nemoclaw-user-configure-security/references/best-practices.md b/skills/nemoclaw-user-configure-security/references/best-practices.md index 59e3ceee9f..7893b472e4 100644 --- a/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -1,24 +1,24 @@ - - # NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw ships with deny-by-default security controls across four layers: network, filesystem, process, and inference. You can tune every control, but each change shifts the risk profile. -This page documents every configurable knob, its default, what it protects, the concrete risk of relaxing it, and a recommendation for common use cases. +This page documents each configurable control, its default, what it protects, the concrete risk of relaxing it, and a recommendation for common use cases. For background on how the layers fit together, refer to How It Works (use the `nemoclaw-user-overview` skill). ## Protection Layers at a Glance NemoClaw enforces security at four layers. -NemoClaw locks some when it creates the sandbox and requires a restart to change them. +NemoClaw locks some controls when it creates the sandbox and requires a restart to change them. You can hot-reload others while the sandbox runs. -The following diagram shows the default posture immediately after `nemoclaw onboard`, before you approve any endpoints or apply any presets. +The following diagram shows the default posture immediately after onboarding, before you approve any endpoints or apply any presets. ```mermaid flowchart TB - subgraph HOST["Your Machine: default posture after nemoclaw onboard"] + subgraph HOST["Your Machine: default posture after onboarding"] direction TB YOU["👤 Operator"] @@ -70,15 +70,16 @@ flowchart TB | Network | Unauthorized outbound connections and data exfiltration. | OpenShell gateway | Yes. Use `openshell policy set` or operator approval. | | Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Use host-side NemoClaw commands for durable config changes. | | Process | Privilege escalation, fork bombs, syscall abuse. | Container runtime (Docker/K8s `securityContext`) | No. Requires sandbox re-creation. | -| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use `nemoclaw inference set`. | +| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use the NemoClaw inference switching command. | ## Network Controls NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets operators approve or deny requests in real time. +Network policy allowlists do not disable OpenShell's SSRF guard; see Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for the interaction between egress rules and internal-address blocking. ### Deny-by-Default Egress -The sandbox blocks all outbound connections unless you explicitly list the endpoint in the policy file `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. +The sandbox blocks all outbound connections unless you explicitly list the endpoint in the applicable baseline policy files. | Aspect | Detail | |---|---| @@ -92,7 +93,7 @@ The sandbox blocks all outbound connections unless you explicitly list the endpo Each network policy entry restricts which executables can reach the endpoint using the `binaries` field. OpenShell identifies the calling binary by reading `/proc//exe` (the kernel-trusted executable path, not `argv[0]`), walking the process tree for ancestor binaries, and computing a SHA256 hash of each binary on first use. -If someone replaces a binary while the sandbox runs, the hash mismatch triggers an immediate deny. +If someone replaces a binary while the sandbox runs, the hash mismatch immediately denies the request. | Aspect | Detail | |---|---| @@ -126,12 +127,12 @@ The `protocol` field on an endpoint controls whether the proxy also inspects ind ### Operator Approval Flow -When the agent reaches an unlisted endpoint, OpenShell blocks the request and prompts the operator in the TUI. +When the agent reaches an unlisted endpoint, OpenShell blocks the request and prompts you in the TUI. | Aspect | Detail | |---|---| | Default | Enabled. The gateway blocks all unlisted endpoints and requires approval. | -| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox (for example, by running `nemoclaw onboard`), the policy resets to the baseline defined in the blueprint. | +| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox through onboarding, the policy resets to the baseline defined in the blueprint. | | Risk if relaxed | Approving an endpoint permanently widens the running sandbox's policy. If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. | | Recommendation | Review each blocked request before approving. If you find yourself approving the same endpoint repeatedly, add it to the baseline policy with appropriate binary and path restrictions. To reset approved endpoints, destroy and recreate the sandbox. | @@ -143,6 +144,7 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for |---|---|---| | `brave` | Brave Search API. | Agent can issue search queries. | | `brew` | Homebrew (Linuxbrew) package manager. The sandbox base image includes the `brew` binary; this preset opens network egress to GitHub and the Homebrew formulae index so `brew install` can fetch bottles. | Allows installing arbitrary Homebrew packages, which may contain malicious code. | +| `claude-code` | Claude Code CLI API, telemetry, and crash-report endpoints. | Allows a separately installed Claude Code CLI to reach Anthropic and telemetry hosts with its own credentials. Do not use this preset for NemoClaw inference routing. | | `discord` | Discord REST API, WebSocket gateway, CDN. | CDN endpoint (`cdn.discordapp.com`) allows GET to any path. WebSocket uses `access: full` (no inspection). | | `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `git`. | | `huggingface` | Hugging Face Hub (download-only) and inference router. | Allows downloading arbitrary models and datasets. POST is restricted to the inference router only. | @@ -173,6 +175,8 @@ The container mounts system directories read-only to prevent the agent from modi ### Agent Config Directory + + The `/sandbox/.openclaw` directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config). The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as `OPENCLAW_GATEWAY_TOKEN`, and writes it to `/tmp/nemoclaw-proxy-env.sh` so interactive sandbox sessions can reach the gateway through system-wide shell hooks. In root mode, the gateway process still runs as the separate `gateway` user, but the token is intentionally available to sandbox shells for local gateway access. @@ -180,10 +184,26 @@ In root mode, the gateway process still runs as the separate `gateway` user, but Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under `/sandbox/.openclaw`. By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. -For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so config and writable state entry points cannot be changed by the sandbox user. +For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so the sandbox user cannot change config and high-risk state entry points. +The immutability workflow locks high-risk state directories (`skills`, `hooks`, `cron`, `agents`, `extensions`, `plugins`, `workspace`, `memory`, `devices`, `canvas`, `telegram`, `wechat`, `whatsapp`, `platforms`, `weixin`, `profiles`, `skins`) to `root:sandbox` with `chmod -R go-w`. +The OpenClaw gateway (a member of the `sandbox` group) keeps read access to plugin and agent code; the sandbox user can no longer write them. +The same workflow also locks the secret-bearing directories (`credentials`, `identity`, `pairing`) to `root:root 700` with `chmod -R go-rwX`. +Neither the sandbox user nor the gateway can read those secrets while the lock is active. +Restoring the mutable-default posture returns both groups to `sandbox:sandbox 2770`. +The list is the union of state directories declared by every shipped agent manifest; the lock helper silently skips dirs that aren't present in a given agent's config tree. +Two exemption kinds keep runtime data writable. +The lock inventory omits top-level Hermes runtime dirs (`sessions/`, `memories/`, `logs/`, `cache/`, `plans/`) and the image-build-regenerated `openclaw-weixin/`; the lock helper never touches those paths. +Inside a locked tree, the helper restores `agents//sessions/` to `sandbox:sandbox 2770` after the surrounding `agents/` lock so the OpenClaw TUI can create and write session metadata under an otherwise root-owned parent. +If any high-risk state-dir root is a symlink when the lock runs, the lock helper refuses to proceed and reports "Config not locked: state dir root is a symlink" instead of following the link with privileged `chown -R` / `chmod -R`. - **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `2770` (setgid `sandbox:sandbox`) and `openclaw.json` with mode `660`, so the agent and its group can read and write config directly. A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked. - **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match. +- **Content integrity seal.** + A clean immutable config lock can capture a SHA-256 seal of `openclaw.json` and other locked files into host-side state. + Verification recomputes hashes inside the sandbox and surfaces drift on mismatch, so a host-root tamper that flips permissions back to `444 root:root` after rewriting the file is still flagged. + Sandboxes locked before the seal landed have no recorded hash; permission-only verification cannot prove their bytes match the image original, so the seal is **not** a retroactive proof of integrity for legacy state. + The same limitation applies when the locked file set grew after the existing seal was captured. + Rebuild the sandbox for a known-good baseline before trusting a new seal. - **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture. | Aspect | Detail | @@ -193,6 +213,25 @@ For sensitive workloads, use a reviewed host-side immutability workflow after in | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | | Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | + + + +The `/sandbox/.hermes` directory contains Hermes runtime configuration, generated environment settings, logs, platform state, and durable database state. +NemoClaw writes `config.yaml` and `.env` during onboarding and rebuilds. +Direct edits to these files can be overwritten when NemoClaw regenerates the image. + +Hermes also stores runtime state such as `state.db`, logs, and platform sessions under the `.hermes` tree. +Messaging sessions such as WhatsApp pairing can remain mutable by design so they survive rebuilds. + +| Aspect | Detail | +|---|---| +| Default | The Hermes config tree contains NemoClaw-generated config plus mutable runtime state. | +| What you can change | Use host-side NemoClaw commands for durable model, provider, messaging, and policy changes; inspect files directly only for debugging. | +| Risk of direct edits | Direct edits to generated config can drift from the host registry and may be lost on rebuild. | +| Recommendation | For sensitive workloads, keep generated config under NemoClaw control and back up Hermes state before destructive operations. | + + + ### Writable Paths The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`. @@ -228,20 +267,28 @@ When the entrypoint switches from root to the `sandbox` and `gateway` users, it The initial entrypoint drop removes `cap_sys_admin`, `cap_sys_ptrace`, `cap_net_raw`, `cap_dac_override`, `cap_sys_chroot`, `cap_fsetid`, `cap_setfcap`, `cap_mknod`, `cap_audit_write`, and `cap_net_bind_service`. During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setgid`, `cap_fowner`, `cap_chown`, and `cap_kill`. -This is best-effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set. +This behavior is best effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set. If `setpriv` is unavailable, the entrypoint falls back to `gosu` and logs a warning that the remaining bounding-set capabilities were retained for the child process. -For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose (see Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill)). + +To make the drop fail-closed instead of best-effort, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment. +The agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities, so it will not boot on a host whose bounding set still holds them — typically one that cannot perform the drop (no `CAP_SETPCAP`, or `capsh` missing) and was not given a clean bounding set by the container runtime. +This is opt-in because such hosts are common (many cloud VMs, Docker Desktop, WSL); leaving it unset preserves the best-effort default. +The check covers the agent process tree only — a `nemoclaw connect` shell is spawned by the container runtime outside that tree and is not affected (tracked in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452)). + + +For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose. Refer to Sandbox Hardening. + | Aspect | Detail | |---|---| | Default | The entrypoint drops dangerous capabilities at startup using `capsh`, then uses `setpriv` during user step-down when possible. Best-effort. | -| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw flow (with `nemoclaw onboard`), the entrypoint handles capability dropping automatically. | +| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw onboarding flow, the entrypoint handles capability dropping automatically. | | Risk if relaxed | `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` expand kernel and process attack surface. `CAP_NET_RAW` allows raw socket access for network sniffing. `CAP_DAC_OVERRIDE` bypasses filesystem permission checks. If `capsh` or `setpriv` cannot run, the container retains more of the runtime-provided capability set. | | Recommendation | Run on an image that includes `capsh` and `setpriv` (the NemoClaw image includes them). For defense-in-depth, also pass `--cap-drop=ALL` at the container runtime level. | ### Gateway Process Isolation -The OpenClaw gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent. +The in-sandbox gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent. | Aspect | Detail | |---|---| @@ -265,7 +312,7 @@ The `no-new-privileges` flag prevents processes from gaining additional privileg A process limit caps the number of processes the sandbox user can spawn. The entrypoint sets both soft and hard limits using `ulimit -u 512`. -This is best-effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit. +This behavior is best effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit. | Aspect | Detail | |---|---| @@ -318,7 +365,7 @@ A registry compromise or accidental force-push cannot silently swap the sandbox | Default | `nemoclaw-blueprint/blueprint.yaml` pins the sandbox image by digest. A CI regression test blocks any mutable-tag reference from merging. | | What you can change | Contributors bumping the sandbox image must update the digest in `blueprint.yaml`. Release tooling should rewrite the digest automatically. | | Risk if relaxed | Reverting to a mutable tag (`:latest`) allows a registry-side change to replace the sandbox image without any blueprint update, which is a supply-chain risk. | -| Recommendation | Always reference the sandbox image by digest. If you build a custom image with `nemoclaw onboard --from`, the digest constraint does not apply to your local build. | +| Recommendation | Always reference the sandbox image by digest. If you build a custom image with the onboarding `--from` path, the digest constraint does not apply to your local build. | ### Auth Profile Permissions @@ -334,6 +381,8 @@ This prevents other users on the host from reading stored credentials. ## Gateway Authentication Controls + + The OpenClaw gateway authenticates devices that connect to the Control UI dashboard. NemoClaw hardens these defaults at image build time. @@ -381,6 +430,15 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | | Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | + + + +Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. +Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. +NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. + + + ### CLI Secret Redaction The CLI automatically redacts secret patterns (API keys, bearer tokens, provider credentials) from command output and error messages before logging them. @@ -390,21 +448,31 @@ The CLI automatically redacts secret patterns (API keys, bearer tokens, provider | Default | Enabled. The runner redacts secrets from stdout, stderr, and thrown error messages. | | What you can change | This is not a user-facing knob. The CLI enforces it on all command output paths. | | Risk if relaxed | Without redaction, secrets could appear in terminal scrollback, log files, or debug output shared in bug reports. | -| Recommendation | No action needed. If you share `nemoclaw debug` output, verify that no secrets appear in the collected diagnostics. | +| Recommendation | No action needed. If you share NemoClaw debug output, verify that no secrets appear in the collected diagnostics. | ### Memory Secret Scanner + + The NemoClaw plugin blocks the agent from writing likely secrets (API keys, tokens, private keys) into persistent memory files. The scanner intercepts Write, Edit, and similar tool calls targeting memory and workspace paths before they reach disk. | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Examples include `.openclaw/memory/`, `.openclaw/workspace/`, `.openclaw/agents/`, `.openclaw/skills/`, `.openclaw/hooks/`, `.openclaw/credentials/`, `.openclaw/openclaw.json`, `.nemoclaw/`, and `MEMORY.md`; the exact coverage is defined by `MEMORY_PATH_SEGMENTS` and enforced through `isMemoryPath()`. | +| What it covers | Three classifiers, all enforced through `isMemoryPath()`: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | + + + +Hermes does not use the OpenClaw NemoClaw plugin memory scanner. +Keep secrets in environment variables or OpenShell providers, and avoid writing raw credentials to Hermes state files or workspace content. + + + ## Inference Controls OpenShell routes all inference traffic through the gateway to isolate provider credentials from the sandbox. @@ -419,7 +487,7 @@ The agent never receives the provider API key. | Default | The agent talks to `inference.local`. The host owns the credential and upstream endpoint. | | What you can change | You cannot configure this architecture. The system always enforces it. | | Risk if bypassed | If the agent could reach an inference endpoint directly (by adding it to the network policy), it would need an API key. Since the sandbox does not contain credentials, this acts as defense-in-depth. However, adding an inference provider's host to the network policy without going through OpenShell routing could let the agent use a stolen or hardcoded key. | -| Recommendation | Do not add inference provider hosts (such as `api.openai.com` or `api.anthropic.com`) to the network policy. Use OpenShell inference routing instead. | +| Recommendation | Do not add inference provider hosts (such as `api.openai.com` or `api.anthropic.com`) to the network policy for NemoClaw model traffic. Use OpenShell inference routing instead. The `claude-code` preset is a separate opt-in exception for running the Claude Code CLI with its own credentials, not a way to configure NemoClaw inference. | ### Provider Trust Tiers @@ -438,12 +506,14 @@ Different inference providers have different trust and cost profiles. ### Experimental Providers -The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and generic Linux managed vLLM install/start. DGX Spark and DGX Station managed vLLM entries are offered by default, and an already-running vLLM server on `localhost:8000` is offered in the menu without a flag, because selecting either is an explicit user action. +The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and generic Linux managed vLLM install/start. +DGX Spark and DGX Station managed vLLM entries appear by default. +An already-running vLLM server on `localhost:8000` also appears in the menu without a flag because selecting it is an explicit user action. | Aspect | Detail | |---|---| | Default | Local NVIDIA NIM and generic Linux managed vLLM install/start are hidden. DGX Spark and DGX Station managed vLLM entries, plus already-running vLLM on `localhost:8000`, are offered when detected. | -| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before running `nemoclaw onboard` to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. | +| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before onboarding to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. | | Risk if selected | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. The managed vLLM path pulls a container image and starts it on a supported NVIDIA GPU host. Misconfiguration can cause failed inference or unexpected behavior. | | Recommendation | Use experimental providers only for evaluation. Do not rely on them for always-on assistants. | @@ -489,16 +559,16 @@ The following patterns weaken security without providing meaningful benefit. | Omitting `protocol: rest` on REST API endpoints without a compatibility reason | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. Use L4 pass-through only for documented cases such as npm/Yarn on Node 22, where the client requires a CONNECT tunnel that L7 inspection would break. | | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. | | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. | -| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Lock config for always-on assistants handling sensitive data. | -| Adding inference provider hosts to the network policy | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. | +| Leaving generated agent config writable on sensitive workloads | The generated config tree contains model routing, channel settings, and runtime integration state (`/sandbox/.openclaw` for OpenClaw, `/sandbox/.hermes` for Hermes). Writable config lets the agent drift from host-managed policy and routing. | Keep generated config under NemoClaw control for always-on assistants handling sensitive data. | +| Adding inference provider hosts to the network policy for NemoClaw inference | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. Apply `claude-code` only when intentionally running the separate Claude Code CLI inside the sandbox. | | Disabling device auth for remote deployments | Without device auth, any device on the network can connect to the gateway without pairing. Combined with a cloudflared tunnel, this makes the dashboard publicly accessible and unauthenticated. | Keep `NEMOCLAW_DISABLE_DEVICE_AUTH` at its default (`0`). Only set it to `1` for local headless or development environments. | ## Known Limitations | Limitation | Impact | Mitigation | |-----------|--------|------------| -| `openclaw agent --local` bypasses gateway | Secret scanning, network policy, and inference auth are not enforced when the agent runs in local mode. | A runtime warning is emitted when `--local` is detected. Avoid `--local` for production workflows. A future OpenClaw-level hook will close this gap. | -| Direct filesystem writes bypass secret scanner | The scanner intercepts OpenClaw tool calls, not raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. The scanner is application-layer defense-in-depth, not a filesystem-level control. | +| Bypassing managed gateway paths | Network policy and inference auth are not enforced when an agent runtime is launched outside the NemoClaw-managed gateway path. | Use NemoClaw-managed sandbox entrypoints for production workflows. | +| Direct filesystem writes bypass application-layer scanners | Application-layer scanners can intercept agent tool calls, not arbitrary raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. Application-layer scanning is defense-in-depth, not a filesystem-level control. | | Base64/hex-encoded secrets are not detected | Content-based regex scanning cannot detect encoded or obfuscated secrets. | Use environment variables or credential stores instead of writing secrets to files. | ## Related Topics @@ -506,6 +576,8 @@ The following patterns weaken security without providing meaningful benefit. - Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference. - Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for static and dynamic policy changes. - Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill) for the operator approval flow. -- Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill) for container-level security measures. + +- Sandbox Hardening for container-level security measures. + - Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details. - How It Works (use the `nemoclaw-user-overview` skill) for the protection layer architecture. diff --git a/skills/nemoclaw-user-configure-security/references/credential-storage.md b/skills/nemoclaw-user-configure-security/references/credential-storage.md index b40b676a20..cdecf97052 100644 --- a/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -1,31 +1,37 @@ - - # Credential Storage +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw does not persist provider credentials to host disk. The OpenShell gateway is the only system of record for stored credentials. -When you provide a provider credential — interactively during `nemoclaw onboard` or via an environment variable — NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. +When you provide a provider credential, either interactively during `nemoclaw onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret. + The sandbox-side OpenClaw gateway token is generated at container startup and is not rotated through provider credential commands. + + +Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. + ## Where Credentials Live Provider credentials live in the OpenShell gateway store. List what is registered with: -```console -$ openshell provider list +```bash +openshell provider list ``` Or, equivalently, through NemoClaw: -```console -$ nemoclaw credentials list +```bash +nemoclaw credentials list ``` -Both surface the provider names that the gateway holds credentials for. The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. +Both commands show the provider names registered with the gateway. +The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. NemoClaw still keeps non-secret operational state under `~/.nemoclaw/` (such as the sandbox registry). That directory is created with mode `0700` and contains no credential material. @@ -39,13 +45,16 @@ This means you can: - 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 +When the host environment is empty, day-two operations such as `nemoclaw rebuild` and remote-provider updates can reuse the credential already registered with the OpenShell gateway. +Export the credential only when you want to create, replace, or rotate the stored provider value. + ## Deploy Reads from Environment Only `nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time. A typical deploy invocation looks like: -```console -$ NVIDIA_API_KEY=nvapi-... \ +```bash +NVIDIA_API_KEY=nvapi-... \ HF_TOKEN=hf_... \ TELEGRAM_BOT_TOKEN=... \ nemoclaw deploy my-instance @@ -61,7 +70,8 @@ When a private repo requires authentication NemoClaw runs `gh auth token`, which The GitHub CLI prefers an OS keychain when one is reachable: macOS Keychain on macOS, Windows Credential Manager on Windows, and Linux Secret Service (libsecret + a running D-Bus session) on Linux. On hosts where no keychain is reachable (CI runners, headless launches, WSL without a session bus, macOS contexts where Keychain access is blocked, etc.) `gh auth login` falls back to a `gh`-managed file under `~/.config/gh/` with mode `0600`. -NemoClaw treats both backends identically: `gh auth token` returns the value, and NemoClaw stages it in `process.env` for the current run only. +NemoClaw treats both backends identically. +`gh auth token` returns the value, and NemoClaw stages it in `process.env` for the current run only. If `gh` is not installed or not logged in, NemoClaw prompts for a personal access token for that single run; the prompted value is held in process memory and is not written to host disk. Run `gh auth login` if you want a persistent backing store (whichever one applies on your host) so future runs do not prompt. @@ -84,14 +94,14 @@ 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: -```console -$ NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard +```bash +NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard ``` To remove a credential from the gateway entirely: -```console -$ nemoclaw credentials reset +```bash +nemoclaw credentials reset ``` `` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure). diff --git a/skills/nemoclaw-user-configure-security/references/openclaw-controls.md b/skills/nemoclaw-user-configure-security/references/openclaw-controls.md index 2ced0c76de..13e31c8702 100644 --- a/skills/nemoclaw-user-configure-security/references/openclaw-controls.md +++ b/skills/nemoclaw-user-configure-security/references/openclaw-controls.md @@ -1,5 +1,3 @@ - - # OpenClaw Security Controls Beyond NemoClaw's Scope NemoClaw provides infrastructure-layer security through sandbox isolation, network policy, filesystem restrictions, SSRF validation, and credential handling. @@ -7,7 +5,7 @@ It delegates all application-layer security to OpenClaw. This page documents areas where NemoClaw adds no independent protection beyond what OpenClaw already provides. The details below reflect the OpenClaw documentation at the time of writing. -Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security/index) for the current state. +Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security) for the current state. ## Prompt Injection Detection and Prevention @@ -58,7 +56,7 @@ OpenClaw blocks environment variables that could enable code injection, privileg ## Security Audit Framework -OpenClaw runs automated security checks (50+ distinct check types) that cover configuration, credential handling, and sandbox posture. +OpenClaw runs more than 50 distinct automated security checks that cover configuration, credential handling, and sandbox posture. Run `openclaw security audit` to see all findings for your deployment. These checks include: @@ -94,7 +92,7 @@ OpenClaw controls who can interact with the agent through direct messages and gr | Control | Detail | |---|---| -| DM policy modes | 4 modes: open, disabled, pairing, allowlist | +| DM policy modes | Four modes: open, disabled, pairing, allowlist | | Group policies | Per-group access rules | | Per-sender authorization | Individual sender gating | | Command authorization | Command-level access control | @@ -112,7 +110,7 @@ OpenClaw restricts what supplemental context the agent can see and how it can mo ## Safe Regex (ReDoS Prevention) -OpenClaw includes safe regex compilation to prevent Regular Expression Denial of Service (ReDoS) attacks. +OpenClaw includes safe regex compilation to prevent regular expression denial of service (ReDoS) attacks. The implementation detects unsafe nested quantifiers, bounds input length, and caches results. ## Next Steps diff --git a/skills/nemoclaw-user-deploy-remote/SKILL.md b/skills/nemoclaw-user-deploy-remote/SKILL.md index d2ac40e834..9885238e64 100644 --- a/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -1,18 +1,15 @@ --- name: "nemoclaw-user-deploy-remote" -description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." +description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw dockerignore, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." license: "Apache-2.0" --- - - - # Deploy NemoClaw to a Remote GPU Instance ## Gotchas - The `nemoclaw deploy` command is deprecated. -- On Brev, set `CHAT_UI_URL` in the launchable environment configuration so it is available when the installer builds the sandbox image. +- On Brev, set `CHAT_UI_URL` in the launchable environment configuration so the installer can read it when it builds the sandbox image. ## Prerequisites @@ -24,20 +21,6 @@ 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`. -## Quick Start - -If your Brev instance is already up and has already been onboarded with a sandbox, start with the standard sandbox chat flow: - -```console -$ nemoclaw my-assistant connect -$ openclaw tui -``` - -This gets you into the sandbox shell first and opens the OpenClaw chat UI right away. -If the VM is fresh, run the standard installer on that host and then run `nemoclaw onboard` before trying `nemoclaw my-assistant connect`. - -If you are connecting from your local machine and still need to provision the remote VM, you can still use `nemoclaw deploy ` as the legacy compatibility path described below. - ## Deploy the Instance **Warning:** @@ -47,8 +30,8 @@ Prefer provisioning the remote host separately, then running the standard NemoCl Create a Brev instance and run the legacy compatibility flow: -```console -$ nemoclaw deploy +```bash +nemoclaw deploy ``` Replace `` with a name for your remote instance, for example `my-gpu-box`. @@ -61,7 +44,7 @@ The legacy compatibility flow performs the following steps on the VM: 1. Installs Docker and the NVIDIA Container Toolkit if a GPU is present. 2. Installs the OpenShell CLI. 3. Runs `nemoclaw onboard` (the setup wizard) to create the gateway, register providers, and launch the sandbox. -4. Starts optional host auxiliary services (for example the cloudflared tunnel) when `cloudflared` is available. Channel messaging is configured during onboarding and runs through OpenShell-managed processes, not through `nemoclaw tunnel start`. +4. Starts optional host auxiliary services, such as the cloudflared tunnel, when `cloudflared` is available. Onboarding configures channel messaging, and the channels run through OpenShell-managed processes, not through `nemoclaw tunnel start`. By default, the compatibility wrapper asks Brev to provision on `gcp`. Override this with `NEMOCLAW_BREV_PROVIDER` if you need a different Brev cloud provider. If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those values to the VM so remote setup can pull gated Hugging Face model repositories. @@ -71,47 +54,43 @@ If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox. To reconnect after closing the session, run the command again: -```console -$ nemoclaw deploy +```bash +nemoclaw deploy ``` ## Monitor the Remote Sandbox SSH to the instance and run the OpenShell TUI to monitor activity and approve network requests: -```console -$ ssh 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term' +```bash +ssh 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term' ``` ## Verify Inference Run a test agent prompt inside the remote sandbox: -```console -$ openclaw agent --agent main -m "Hello from the remote sandbox" --session-id test +```bash +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 accessing 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 will use **before** running setup: +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: -```console -$ export CHAT_UI_URL="https://openclaw0-.brevlab.com" -$ nemoclaw deploy +```bash +export CHAT_UI_URL="https://openclaw0-.brevlab.com" +nemoclaw deploy ``` -For SSH port-forwarding, the origin is typically `http://127.0.0.1:18789` (the -default), so no extra configuration is needed. +For SSH port-forwarding, the origin is typically the default `http://127.0.0.1:18789`, so you do not need extra configuration. **Warning:** -On Brev, set `CHAT_UI_URL` in the launchable environment configuration so it is -available when the installer builds the sandbox image. If `CHAT_UI_URL` is not -set on a headless host, the compatibility wrapper prints a warning. +On Brev, set `CHAT_UI_URL` in the launchable environment configuration so the installer can read it when it builds the sandbox image. +If you do not set `CHAT_UI_URL` on a headless host, the compatibility wrapper prints a warning. `NEMOCLAW_DISABLE_DEVICE_AUTH` is also evaluated at image build time. When `CHAT_UI_URL` points at a non-loopback origin, NemoClaw disables OpenClaw device pairing in the generated sandbox configuration because browser-only remote users cannot complete terminal-based pairing. @@ -119,37 +98,37 @@ Any device that can reach the configured dashboard origin can connect without pa ## First-Run Readiness Budget -On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the sandbox image is built locally and uploaded into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts. -The post-create readiness wait defaults to 180 seconds (`NEMOCLAW_SANDBOX_READY_TIMEOUT`), which is sized for warm-cache, workstation-class onboarding and can be exceeded on: +On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the host builds the sandbox image locally and uploads it into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts. +The post-create readiness wait defaults to 180 seconds (`NEMOCLAW_SANDBOX_READY_TIMEOUT`), which fits warm-cache, workstation-class onboarding but can be too short for: -- DGX Station first runs with large quantised models (70B+ parameter footprints, NVFP4 weights). +- DGX Station first runs with large quantized models (70B+ parameter footprints, NVFP4 weights). - Cloud VMs where the local image-build cache is cold and the upload runs over the public network. - Hosts onboarding the Brave Web Search preset on the first run (the egress policy stack adds boot work). Raise the budget before re-running onboard: -```console -$ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -$ nemoclaw onboard +```bash +export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 +nemoclaw onboard ``` -If onboard ends with `Sandbox '' was created but did not become ready within 180s`, onboard deletes the partially-created sandbox first, so the next attempt with the raised budget starts from a clean state. -For the inference-probe budget that runs earlier in onboarding, see `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` (use the `nemoclaw-user-configure-inference` skill). +If onboard ends with `Sandbox '' was created but did not become ready within 180s`, onboard first deletes the partially created sandbox, so the next attempt with the raised budget starts from a clean state. +For the inference-probe budget that runs earlier in onboarding, refer to `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` (use the `nemoclaw-user-configure-inference` skill). ## Proxy Configuration NemoClaw routes sandbox traffic through a gateway proxy that defaults to `10.200.0.1:3128`. If your network requires a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding: -```console -$ export NEMOCLAW_PROXY_HOST=proxy.example.com -$ export NEMOCLAW_PROXY_PORT=8080 -$ nemoclaw onboard +```bash +export NEMOCLAW_PROXY_HOST=proxy.example.com +export NEMOCLAW_PROXY_PORT=8080 +nemoclaw onboard ``` -These values are baked into the sandbox image at build time. -They are also forwarded into the runtime container during sandbox creation, so `/tmp/nemoclaw-proxy-env.sh` uses the same host and port that the image build used. -Only alphanumeric characters, dots, hyphens, and colons are accepted for the host. +NemoClaw bakes these values into the sandbox image at build time. +NemoClaw also forwards them into the runtime container during sandbox creation, so `/tmp/nemoclaw-proxy-env.sh` uses the same host and port that the image build used. +NemoClaw accepts only alphanumeric characters, dots, hyphens, and colons for the host. The port must be numeric (0-65535). Changing the proxy after onboarding requires re-running `nemoclaw onboard`. @@ -159,14 +138,14 @@ The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`. Set this variable before running `nemoclaw deploy` to use a different GPU configuration: -```console -$ export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" -$ nemoclaw deploy +```bash +export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" +nemoclaw deploy ``` ## References -- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox. +- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox, including `.dockerignore` handling for custom build contexts. - **Load [references/brev-web-ui.md](references/brev-web-ui.md)** when a user wants to try NemoClaw without installing the CLI, or asks how to get started on Brev. Guides users through deploying NemoClaw with the Brev web UI. - **Load [references/sandbox-hardening.md](references/sandbox-hardening.md)** when reviewing sandbox image security controls, auditing capability drops, or looking up the runtime resource limits. Includes the sandbox container image hardening reference, covering Docker capabilities and process limits. @@ -174,4 +153,4 @@ $ nemoclaw deploy - `nemoclaw-user-manage-sandboxes` — Set Up Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) to connect Telegram, Discord, or Slack through OpenShell-managed channel messaging - `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for sandbox monitoring tools -- `nemoclaw-user-reference` — Commands (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference +- `nemoclaw-user-reference` — `nemoclaw deploy` (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference diff --git a/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md b/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md index 517e14b48d..f0059b3c54 100644 --- a/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md +++ b/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md @@ -1,5 +1,3 @@ - - # Launch NemoClaw with the Brev Web UI Use the Brev web UI to launch a hosted NemoClaw sandbox from your browser. @@ -29,7 +27,8 @@ You do not need to install local software for this flow. ## Get Your NVIDIA API Key -If you already have an NVIDIA API key skip this section. Otherwise, follow these steps to generate a new key: +If you already have an NVIDIA API key, skip this section. +Otherwise, follow these steps to generate a new key: 1. Go to [build.nvidia.com](https://build.nvidia.com). 2. Sign in or create an account. @@ -48,7 +47,7 @@ Use the [NemoClaw Brev launchable](https://brev.nvidia.com/launchable/deploy/now 2. Review the instance type, cloud provider, and estimated hourly cost on the NemoClaw setup page. 3. Click **Deploy NemoClaw**. -The right-side deployment panel shows progress while Brev deploys the CPU instance and prepares VM mode. +The deployment panel on the right shows progress while Brev deploys the CPU instance and prepares VM mode. Keep this page open until the deployment completes. When the panel shows the **NemoClaw** button, click it to open the agent setup page. @@ -98,7 +97,8 @@ Click **Chat With Agent** to open the OpenClaw dashboard. The dashboard might initially show a **Pairing required** warning. This means the gateway is still completing pairing in the background. -Wait for about a few minutes for pairing to finish automatically. Refresh the dashboard to see if the warning is resolved and the connection is established. +Wait a few minutes for pairing to finish automatically. +Refresh the dashboard to check whether the warning has cleared and the dashboard has connected. If pairing does not finish, go to the **Overview** page in the OpenClaw UI, find the **Gateway Access** panel, and click **Connect**. ## Start a Chat @@ -110,7 +110,7 @@ Hello! What can you do for me? What skills do you have available? ``` The agent reads its workspace files and introduces itself. -The starter workspace includes example skills such as: +The starter workspace includes these example skills: - **Weather** gets current weather and forecasts. - **Healthcheck** runs security audit and hardening checks. diff --git a/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md b/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md index b4b2f5beb8..6f8e721920 100644 --- a/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md +++ b/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md @@ -1,22 +1,20 @@ - - # Install OpenClaw Plugins -OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or -provider integrations. They are different from NemoClaw-managed agent skills: +OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or provider integrations. +They are different from NemoClaw-managed agent skills: - **Plugins** are code packages loaded by OpenClaw. - **Skills** are `SKILL.md` directories that teach an agent how to perform a task. - **Policy presets** are network-egress rules that control what sandboxed code can reach. -Today, the supported NemoClaw path for OpenClaw plugins is to bake the plugin -into a custom sandbox image and onboard from that Dockerfile. +The supported NemoClaw path for OpenClaw plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. ## Prepare a Build Directory Put the Dockerfile and everything it needs to `COPY` in one directory. -`nemoclaw onboard --from ` uses the Dockerfile's parent directory as -the Docker build context. +`nemoclaw onboard --from ` uses the Dockerfile's parent directory as the Docker build context. +Add a `.dockerignore` next to the Dockerfile to exclude local caches, generated artifacts, model files, or other paths that are not needed by the image build. +NemoClaw still applies its own secret-safety exclusions for credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` negates them. ```text my-plugin-sandbox/ @@ -28,8 +26,7 @@ my-plugin-sandbox/ ## Example Dockerfile -Use the custom image to copy the plugin into the OpenClaw extensions directory -and let OpenClaw refresh its config before NemoClaw starts the sandbox. +Use the custom image to copy the plugin into the OpenClaw extensions directory and let OpenClaw refresh its config before NemoClaw starts the sandbox. ```dockerfile ARG SANDBOX_BASE=ghcr.io/nvidia/nemoclaw/sandbox-base:latest @@ -46,48 +43,38 @@ RUN mkdir -p /sandbox/.openclaw/extensions \ WORKDIR /opt/nemoclaw ``` -If the plugin needs configuration in `openclaw.json`, apply it after -`openclaw doctor --fix` so the base config exists first. +If the plugin needs configuration in `openclaw.json`, apply it after `openclaw doctor --fix` so the base config exists first. ## Create the Sandbox Point `nemoclaw onboard --from` at the Dockerfile in the build directory. -```console -$ nemoclaw onboard --from ./my-plugin-sandbox/Dockerfile +```bash +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. +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. ## Network Access -Plugins still run inside the sandbox policy boundary. If a plugin needs network -egress, add or update a policy preset for the required hostnames and binaries -before rebuilding the sandbox. +Plugins still run inside the sandbox policy boundary. +If a plugin needs network egress, add or update a policy preset for the required hostnames and binaries before rebuilding the sandbox. -For example, see Network Policies (use the `nemoclaw-user-reference` skill) for -policy concepts and Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) -for custom preset workflows. +For policy concepts, refer to Network Policies (use the `nemoclaw-user-reference` skill). +For custom preset workflows, refer to Customize Network Policy (use the `nemoclaw-user-manage-policy` skill). ## Common Mistakes -These are the most common places where plugin installation gets mixed up with -other NemoClaw extension paths. +These are the most common places where plugin installation gets mixed up with other NemoClaw extension paths. -- Do not use `nemoclaw skill install` for OpenClaw plugins. That - command only installs `SKILL.md` agent skills. -- Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend - to send that whole directory as the Docker build context. +- Do not use `nemoclaw skill install` for OpenClaw plugins. That command only installs `SKILL.md` agent skills. +- Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend to send that whole directory as the Docker build context. +- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. - Keep plugin dependencies in the build stage or plugin directory; avoid copying unrelated host files into the sandbox image. ## Next Steps -- Review [Sandbox Hardening](sandbox-hardening.md) before adding plugin code to a - shared or long-lived sandbox. -- Review Network Policies (use the `nemoclaw-user-reference` skill) to plan plugin - egress rules. -- Follow Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) - if the plugin needs a custom preset. +- Review [Sandbox Hardening](sandbox-hardening.md) before adding plugin code to a shared or long-lived sandbox. +- Review Network Policies (use the `nemoclaw-user-reference` skill) to plan plugin egress rules. +- Follow Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) if the plugin needs a custom preset. diff --git a/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md b/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md index 669096f180..11937ecd8f 100644 --- a/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md +++ b/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md @@ -1,50 +1,45 @@ - - # Sandbox Image Hardening -The NemoClaw sandbox image applies several security measures to reduce attack -surface and limit the blast radius of untrusted workloads. +The NemoClaw sandbox image applies several security measures to reduce attack surface and limit the blast radius of untrusted workloads. ## Removed Unnecessary Tools -Build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) are -explicitly purged from the runtime image. These tools are not needed at runtime -and would unnecessarily widen the attack surface. +NemoClaw explicitly purges build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image. +These tools are not needed at runtime and would unnecessarily widen the attack surface. -The runtime image keeps a small set of operational utilities for normal sandbox -workflows, including `vi`, `jq`, and `dos2unix`. Use these for lightweight -inspection and file cleanup inside the sandbox, but make durable image or policy -changes in the NemoClaw source tree and rebuild the sandbox. +The runtime image keeps a small set of operational utilities for normal sandbox workflows, including `vi`, `jq`, and `dos2unix`. +Use these utilities for lightweight inspection and file cleanup inside the sandbox, but make durable image or policy changes in the NemoClaw source tree and rebuild the sandbox. -If you need a compiler during build, use the existing multi-stage build -(the `builder` stage has full Node.js tooling) and copy only artifacts into the -runtime stage. +If you need a compiler during build, use the existing multi-stage build. +The `builder` stage has full Node.js tooling. +Copy only artifacts into the runtime stage. ## Process Limits -The container ENTRYPOINT sets `ulimit -u 512` to cap the number of processes -a sandbox user can spawn. This mitigates fork-bomb attacks. The startup script -(`nemoclaw-start.sh`) applies the same limit. +The container ENTRYPOINT sets `ulimit -u 512` to cap the number of processes a sandbox user can spawn. +This mitigates fork-bomb attacks. +The startup script (`nemoclaw-start.sh`) applies the same limit. -Adjust the value via the `--ulimit nproc=512:512` flag if launching with -`docker run` directly. +Adjust the value with the `--ulimit nproc=512:512` flag if you launch with `docker run` directly. ## Dropping Linux Capabilities -The NemoClaw entrypoint drops dangerous capabilities from the process bounding -set before it starts agent services. +The NemoClaw entrypoint drops dangerous capabilities from the process bounding set before it starts agent services. It removes `CAP_SYS_ADMIN`, `CAP_SYS_PTRACE`, `CAP_NET_RAW`, `CAP_DAC_OVERRIDE`, `CAP_SYS_CHROOT`, `CAP_FSETID`, `CAP_SETFCAP`, `CAP_MKNOD`, `CAP_AUDIT_WRITE`, and `CAP_NET_BIND_SERVICE`. -When `setpriv` is available, the entrypoint also removes the remaining -privilege-separation capabilities during the switch from root to the -`sandbox` and `gateway` users. +When `setpriv` is available, the entrypoint also removes the remaining privilege-separation capabilities during the switch from root to the `sandbox` and `gateway` users. + +The bounding-set drop is best effort: if `capsh` or `CAP_SETPCAP` is unavailable the entrypoint logs a warning and continues with the runtime-provided capability set. +If `setpriv` is unavailable, the entrypoint falls back to `gosu`. +To make the drop fail-closed instead, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment: the agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities. +This is opt-in because hosts that cannot drop capabilities (no `CAP_SETPCAP` — many cloud VMs, Docker Desktop, WSL) are common, and the check covers the agent process tree only. For defense-in-depth, also drop all Linux capabilities at the container runtime when you launch the image directly: -```console -$ docker run --rm \ +```bash +docker run --rm \ --cap-drop=ALL \ --ulimit nproc=512:512 \ nemoclaw-sandbox @@ -83,11 +78,15 @@ The agent's home directory (`/sandbox`) is writable by default: | Path | Access | Purpose | |------|--------|---------| -| `/sandbox` | read-write | Home directory — agents can create files and use standard home paths | +| `/sandbox` | read-write | Home directory where agents can create files and use standard home paths | | `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins | -| `/sandbox/.nemoclaw` | read-write | Plugin state and config; blueprints within are DAC-protected (root-owned) | +| `/sandbox/.nemoclaw` | read-write (Landlock); DAC-restricted | Parent directory is `root:root` mode `1755`; the sandbox user can write only to `state/`, `migration/`, `snapshots/`, `staging/`, and `config.json`. `blueprints/` and the parent itself are root-owned to prevent tampering. | | `/tmp` | read-write | Temporary files and logs | +The `Access` column reflects the Landlock policy declaration only. +Actual write success additionally requires POSIX (DAC) ownership and permissions to allow it. +For example, Landlock lists `/sandbox/.nemoclaw` as writable, but the sandbox user cannot create files directly under it because the parent directory is root-owned; writes must target the sandbox-owned subdirectories listed above. + This writable default is intentional. Seeing the sandbox user create files under `/sandbox` or `/sandbox/.openclaw` in a fresh sandbox does not mean Landlock failed. Landlock still enforces the fixed read-only system paths below. @@ -99,7 +98,7 @@ System paths remain read-only to prevent agents from: - Tampering with libraries or shell configuration outside `/sandbox` The image build pre-creates locked shell init files `.bashrc` and `.profile` without proxy entries. -Runtime proxy configuration is sourced from system-wide shell hooks that read `/tmp/nemoclaw-proxy-env.sh`. +System-wide shell hooks that read `/tmp/nemoclaw-proxy-env.sh` source the runtime proxy configuration. ### Landlock Kernel Requirements @@ -111,8 +110,8 @@ Files outside the writable paths would be inaccessible to the agent regardless o Operators should verify Landlock availability: -```console -$ ls /sys/kernel/security/landlock +```bash +ls /sys/kernel/security/landlock ``` For production deployments, kernel 5.13+ with Landlock enabled is strongly recommended. diff --git a/skills/nemoclaw-user-get-started/SKILL.md b/skills/nemoclaw-user-get-started/SKILL.md index 97439a5b6f..c720ad2d2c 100644 --- a/skills/nemoclaw-user-get-started/SKILL.md +++ b/skills/nemoclaw-user-get-started/SKILL.md @@ -3,15 +3,22 @@ name: "nemoclaw-user-get-started" description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop." license: "Apache-2.0" --- + # NemoClaw Quickstart with OpenClaw Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent. **Note:** -Make sure you have completed reviewing the [Prerequisites](references/prerequisites.md) before following this guide. +Review the [Prerequisites](references/prerequisites.md) before following this guide. + +**Use Agent Skills:** -## Install NemoClaw and Onboard OpenClaw Agent +NemoClaw ships user skills for AI coding assistants. +Load them when you want your assistant to walk through installation, inference choices, policy approvals, monitoring, or troubleshooting with NemoClaw-specific guidance. +Refer to Agent Skills (use the `nemoclaw-user-agent-skills` skill). + +## Install NemoClaw and Onboard an OpenClaw Agent Download and run the installer script. The script installs Node.js if it is not already present, then runs the guided onboard wizard to create a sandbox, configure inference, and apply security policies. @@ -24,34 +31,51 @@ NemoClaw creates a fresh OpenClaw instance inside the sandbox during the onboard curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -The piped installer prompts through your terminal. In headless scripts or CI, -pass explicit acceptance to the `bash` side of the pipe: +The third-party software notice runs before the installer installs Node.js or the NemoClaw CLI. +The piped installer can prompt through your terminal when a TTY is available. +In non-TTY contexts, such as CI, an SSH command with piped stdin, or a shell script, pass explicit acceptance to the `bash` side of the pipe: + +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +``` + +Or pass the installer flag through `bash -s`: -```console -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software ``` +To run both installation and onboarding without prompts, also set non-interactive mode and the provider variables your chosen inference path requires: + +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +``` + +Do not place `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1` before `curl`. +In `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 curl ... | bash`, the variable applies only to `curl`, so the installer process cannot see the acceptance. + If you use nvm or fnm to manage Node.js, the installer might not update your current shell's PATH. If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal. On Linux, the installer checks Docker before it installs NemoClaw. If Docker is missing, the installer downloads the official Docker convenience script, asks for `sudo`, installs Docker, and starts the Docker service when systemd is available. -If Docker is installed but your current shell cannot use the Docker socket yet, the installer adds your user to the `docker` group when needed and exits with a recovery command. +If you installed Docker but your current shell cannot use the Docker socket yet, the installer adds your user to the `docker` group when needed and exits with a recovery command. On macOS, the installer uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima. -```console -$ newgrp docker -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```bash +newgrp docker +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. +On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. -The installer auto-launches `nemoclaw onboard` when it can locate the freshly-installed binary. +The installer auto-launches `nemoclaw onboard` when it can locate the freshly installed binary. If it cannot locate the binary, or if blocking host preflight checks fail, it does not launch the wizard automatically. In that case, the installer prints the relevant diagnostics and a `To finish setup, run:` block with the explicit `nemoclaw onboard` command. @@ -61,6 +85,59 @@ The onboard flow builds the sandbox image with `NEMOCLAW_DISABLE_DEVICE_AUTH=1` This is a build-time setting baked into the sandbox image, not a runtime knob. If you export `NEMOCLAW_DISABLE_DEVICE_AUTH` after onboarding finishes, it has no effect on an existing sandbox. +### Respond to the Onboard Wizard + +After the installer launches `nemoclaw onboard`, the wizard runs preflight checks, starts or reuses the OpenShell gateway, asks for an inference provider and model, collects any required credential, then asks for the sandbox name. +It prints a review summary before it registers the provider with OpenShell. +After you confirm, NemoClaw registers inference, prompts for optional web search and messaging channels, builds and starts the sandbox, sets up OpenClaw, then applies the selected network policy tier and presets. +At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. +If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches. + +The inference provider prompt presents a numbered list. + +```text + 1) NVIDIA Endpoints + 2) OpenAI + 3) Other OpenAI-compatible endpoint + 4) Anthropic + 5) Other Anthropic-compatible endpoint + 6) Google Gemini + 7) Local Ollama (localhost:11434) + 8) Model Router (experimental) + Choose [1]: +``` + +Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. +For the full list of providers and validation behavior, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). +Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. +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`. +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 + +Pick the option that matches where you want inference traffic to go. +For full provider behavior, curated models, validation details, and local-runtime setup notes, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). +For Ollama, vLLM, NIM, and compatible local servers, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). + +| Option | Use when | Credential variable | +|---|---|---| +| NVIDIA Endpoints | You want hosted models from `build.nvidia.com`, including hosted Nemotron models. | `NVIDIA_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` | + +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. + ### Review the Configuration Before the Sandbox Build After you enter the sandbox name, the wizard prints a review summary and asks for final confirmation before registering the provider, prompting for optional integrations, and building the sandbox image. @@ -72,8 +149,9 @@ For example, if you picked an OpenAI-compatible endpoint, the summary looks like ────────────────────────────────────────────────── Provider: compatible-endpoint Model: openai/openai/gpt-5.5 - API key: COMPATIBLE_API_KEY (staged for OpenShell gateway registration) + API key: configured for OpenShell gateway registration Web search: disabled + Managed tools: none Messaging: none Sandbox name: my-gpt-claw Note: Sandbox build typically takes 5–15 minutes on this host. @@ -82,7 +160,7 @@ For example, if you picked an OpenAI-compatible endpoint, the summary looks like Apply this configuration? [Y/n]: ``` -The default is `Y`, so you can press Enter once to continue. Answer `n` to abort cleanly, fix the entries, and re-run `nemoclaw onboard`. +The default is `Y`, so you can press Enter one time to continue. Answer `n` to abort cleanly, fix the entries, and re-run `nemoclaw onboard`. Non-interactive runs (`NEMOCLAW_NON_INTERACTIVE=1`) print the summary for log clarity but skip the prompt. @@ -94,6 +172,7 @@ If you enable it, enter a Brave Search API key when prompted. The wizard also offers messaging channels such as Telegram, Discord, Slack, WeChat, and WhatsApp. Press a channel number to toggle it, then press Enter to continue. +If you leave all channels unselected, pressing Enter skips messaging setup. If you select a channel, NemoClaw validates the token format before it bakes the channel configuration into the sandbox. For example, Slack bot tokens must start with `xoxb-`. WeChat and WhatsApp are experimental. @@ -102,6 +181,7 @@ Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) befor ### Choose Network Policy Presets After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. +Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. @@ -110,7 +190,7 @@ Press `r` to toggle a selected preset between read-only and read-write when the When the install completes, a summary confirms the running environment. Before printing the summary, NemoClaw verifies that the sandbox gateway and dashboard port forward are reachable. -Inference route and messaging bridge checks are reported as warnings when they need more time or additional configuration. +NemoClaw reports inference route and messaging bridge checks as warnings when they need more time or additional configuration. The `Model` and provider line reflects the inference option you picked during onboarding. The example below shows the result if you picked an OpenAI-compatible endpoint during onboarding. @@ -147,8 +227,6 @@ Manage later If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, `nvidia-routed (Model Router)`, or ` (Other OpenAI-compatible endpoint)`. -Load [references/quickstart-details.md](references/quickstart-details.md) for detailed steps on Respond to the Onboard Wizard. - ## Run Your First Agent Prompt You can chat with the agent from the terminal or the browser. @@ -158,7 +236,7 @@ You can chat with the agent from the terminal or the browser. The onboard wizard starts a background port forward to the sandbox dashboard, then prints the dashboard URL in the install summary. The default host port is `18789`. If that port is already taken, NemoClaw uses the next free dashboard port, such as `18790`, and prints that port in the final URL. -If the chosen port becomes occupied after the sandbox build starts, onboarding rolls back the newly-created sandbox and asks you to retry instead of printing an unreachable dashboard URL. +If the chosen port becomes occupied after the sandbox build starts, onboarding rolls back the newly created sandbox and asks you to retry instead of printing an unreachable dashboard URL. The install transcript does not print the gateway token. If the browser requires authentication, use the `dashboard-url --quiet` command to print a complete URL explicitly. @@ -182,11 +260,11 @@ openclaw tui ## References -- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes API endpoint. +- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes dashboard and API endpoint. - **Load [references/prerequisites.md](references/prerequisites.md)** when verifying prerequisites before installation. Lists the hardware, software, and container runtime requirements for running NemoClaw. - **Load [references/windows-preparation.md](references/windows-preparation.md)** when preparing a Windows machine for NemoClaw, enabling WSL 2, configuring Docker Desktop for Windows, or troubleshooting a Windows-specific install error. Covers Windows-only preparation steps required before the Quickstart. -- **Load [references/quickstart-details.md](references/quickstart-details.md)** when you need detailed steps for Respond to the Onboard Wizard. ## Related Skills - `nemoclaw-user-overview` — NemoClaw Overview (use the `nemoclaw-user-overview` skill) to learn what NemoClaw is and its capabilities +- `nemoclaw-user-agent-skills` — Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant diff --git a/skills/nemoclaw-user-get-started/references/prerequisites.md b/skills/nemoclaw-user-get-started/references/prerequisites.md index 776cba7577..4e7b25437f 100644 --- a/skills/nemoclaw-user-get-started/references/prerequisites.md +++ b/skills/nemoclaw-user-get-started/references/prerequisites.md @@ -1,6 +1,6 @@ # Prerequisites -Before getting started, check the prerequisites to ensure you have the necessary software and hardware to run NemoClaw. +Before you start, verify that your machine has the software and hardware needed to run NemoClaw. ## Hardware @@ -10,7 +10,11 @@ Before getting started, check the prerequisites to ensure you have the necessary | RAM | 8 GB | 16 GB | | Disk | 20 GB free | 40 GB free | -The sandbox image is approximately 2.4 GB compressed. During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline. The pipeline buffers decompressed layers in memory. On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. If you cannot add memory, configuring at least 8 GB of swap can work around the issue at the cost of slower performance. +The sandbox image is approximately 2.4 GB compressed. +During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline. +The pipeline buffers decompressed layers in memory. +On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. +If you cannot add memory, configure at least 8 GB of swap to work around the issue at the cost of slower performance. ## Software @@ -24,8 +28,9 @@ The sandbox image is approximately 2.4 GB compressed. During image push, the Doc On Linux, the installer can install Docker, start the Docker service, and add your user to the `docker` group. If the group change is not active in the current shell, the installer exits with `newgrp docker` guidance before it starts onboarding. If you choose the native Linux Ollama install path, the onboard wizard also requires `zstd` for Ollama archive extraction. +The installer also requires `strings` from `binutils` to verify the OpenShell binary before it continues with OpenShell install work. -**Docker group access:** +**Docker Group Access:** NemoClaw needs Docker access. On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo. @@ -33,6 +38,11 @@ Members of the `docker` group can control the daemon with root-level impact, so For background, review Docker's [daemon attack surface guidance](https://docs.docker.com/engine/security/#docker-daemon-attack-surface). On Debian and Ubuntu, NemoClaw installs `zstd` with `apt-get` if it is missing; on other Linux distributions, install `zstd` before onboarding. +If the installer reports that `strings` is missing, install `binutils` and rerun the installer: + +```bash +sudo apt-get install -y binutils +``` On macOS, NemoClaw uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima. You do not need to install or sign a separate OpenShell VM driver helper for standard macOS onboarding. @@ -42,17 +52,17 @@ You do not need to install or sign a separate OpenShell VM driver helper for sta 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`. -**Docker storage driver:** +**Docker Storage Driver:** On Linux hosts running Docker 26 or later with the [containerd image store](https://docs.docker.com/engine/storage/containerd/) enabled (the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros), `nemoclaw onboard` transparently builds a `fuse-overlayfs`-enabled cluster image to bypass a kernel-level nested-overlay limitation in k3s. -No manual setup is required. -See the troubleshooting guide (use the `nemoclaw-user-reference` skill) for the override knobs and a manual `daemon.json` alternative. +You do not need manual setup. +Refer to the troubleshooting guide (use the `nemoclaw-user-reference` skill) for the override knobs and a manual `daemon.json` alternative. ## Platforms The following table lists tested platform and runtime combinations. Availability is not limited to these entries, but untested configurations can have issues. -The table is generated from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. +The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. | OS | Container runtime | Status | Notes | |----|-------------------|--------|-------| @@ -63,5 +73,6 @@ The table is generated from [`ci/platform-matrix.json`](https://github.com/NVIDI ## Next Steps -- [Prepare Windows for NemoClaw](windows-preparation.md) if you are using Windows. -- [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandbox. +- Prepare Windows for NemoClaw if you are using Windows. +- [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandboxed agent. +- Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant before setup. diff --git a/skills/nemoclaw-user-get-started/references/quickstart-details.md b/skills/nemoclaw-user-get-started/references/quickstart-details.md deleted file mode 100644 index 1caf356ffb..0000000000 --- a/skills/nemoclaw-user-get-started/references/quickstart-details.md +++ /dev/null @@ -1,165 +0,0 @@ -# NemoClaw Quickstart with OpenClaw: Details - -## Respond to the Onboard Wizard - -After the installer launches `nemoclaw onboard`, the wizard runs preflight checks, starts or reuses the OpenShell gateway, and asks for an inference provider, sandbox name, optional web search, optional messaging channels, and network policy presets. -At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. -If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches. - -The inference provider prompt presents a numbered list. - -```text - 1) NVIDIA Endpoints - 2) OpenAI - 3) Other OpenAI-compatible endpoint - 4) Anthropic - 5) Other Anthropic-compatible endpoint - 6) Google Gemini - 7) Local Ollama (localhost:11434) - 8) Model Router (experimental) - Choose [1]: -``` - -Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. -For the full list of providers and validation behavior, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). -Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. -The Model Router option appears when the blueprint router profile is enabled. - -**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`. -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. - -**Option 1: NVIDIA Endpoints:** - -Routes inference to models hosted on [build.nvidia.com](https://build.nvidia.com). - -Use `NVIDIA_API_KEY` for the API key. Get one from the [NVIDIA build API keys page](https://build.nvidia.com/settings/api-keys). - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, press Enter (or type `1`) to select **NVIDIA Endpoints**. -2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. -3. At the `Choose model [1]:` prompt, pick a curated model from the list (for example, `Nemotron 3 Super 120B`, `GLM-5`, `MiniMax M2.7`, `GPT-OSS 120B`, or `DeepSeek V4 Pro`), or pick `Other...` to enter any model ID from the [NVIDIA Endpoints catalog](https://build.nvidia.com). - -NemoClaw validates the model against the catalog API before creating the sandbox. - -**Tip:** - -Use this option for Nemotron and other models hosted on `build.nvidia.com`. If you run NVIDIA Nemotron from a self-hosted NIM, an enterprise gateway, or any other endpoint, choose **Option 3** instead, since all Nemotron models expose OpenAI-compatible APIs. - -**Option 2: OpenAI:** - -Routes inference to the OpenAI API at `https://api.openai.com/v1`. - -Use `OPENAI_API_KEY` for the API key. Get one from the [OpenAI API keys page](https://platform.openai.com/api-keys). - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `2` to select **OpenAI**. -2. At the `OPENAI_API_KEY:` prompt, paste your key if it is not already exported. -3. At the `Choose model [1]:` prompt, pick a curated model (for example, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, or `gpt-5.4-pro-2026-03-05`), or pick **Other...** to enter any OpenAI model ID. - -**Option 3: Other OpenAI-Compatible Endpoint:** - -Routes inference to any server that implements `/v1/chat/completions`, including OpenRouter, LocalAI, llama.cpp, vLLM behind a proxy, and any compatible gateway. - -Use `COMPATIBLE_API_KEY` for the API key. Set it to whatever credential your endpoint expects. If your endpoint does not require auth, use any non-empty placeholder. - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `3` to select **Other OpenAI-compatible endpoint**. -2. At the `OpenAI-compatible base URL` prompt, enter the provider's base URL. Find the exact value in your provider's API documentation. NemoClaw appends `/v1` automatically, so leave that suffix off. -3. At the `COMPATIBLE_API_KEY:` prompt, paste your key if it is not already exported. -4. At the `Other OpenAI-compatible endpoint model []:` prompt, enter the model ID exactly as it appears in your provider's model catalog. - -For example, when you use NVIDIA's OpenAI-compatible inference endpoint, enter `https://inference-api.nvidia.com` as the base URL and the model ID your endpoint exposes, such as `openai/openai/gpt-5.5`. - -NemoClaw sends a real inference request to validate the endpoint and model. -If the endpoint does not return the streaming events OpenClaw needs from the Responses API, NemoClaw falls back to the chat completions API and configures OpenClaw to use `openai-completions`. - -**Tip:** - -NVIDIA Nemotron models expose OpenAI-compatible APIs, so this option is the right choice for any Nemotron deployment that does not live on `build.nvidia.com`. Common examples include a self-hosted NIM container, an enterprise NVIDIA AI Enterprise gateway, or a vLLM/SGLang server running Nemotron weights. Point the base URL at your endpoint and enter the Nemotron model ID exactly as your server reports it. - -**Option 4: Anthropic:** - -Routes inference to the Anthropic Messages API at `https://api.anthropic.com`. - -Use `ANTHROPIC_API_KEY` for the API key. Get one from the [Anthropic console keys page](https://console.anthropic.com/settings/keys). - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `4` to select **Anthropic**. -2. At the `ANTHROPIC_API_KEY:` prompt, paste your key if it is not already exported. -3. At the `Choose model [1]:` prompt, pick a curated model (for example, `claude-sonnet-4-6`, `claude-haiku-4-5`, or `claude-opus-4-6`), or pick **Other...** to enter any Claude model ID. - -**Option 5: Other Anthropic-Compatible Endpoint:** - -Routes inference to any server that implements the Anthropic Messages API at `/v1/messages`, including Claude proxies, Bedrock-compatible gateways, and self-hosted Anthropic-compatible servers. - -Use `COMPATIBLE_ANTHROPIC_API_KEY` for the API key. Set it to whatever credential your endpoint expects. - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `5` to select **Other Anthropic-compatible endpoint**. -2. At the `Anthropic-compatible base URL` prompt, enter the proxy or gateway's base URL from its documentation. -3. At the `COMPATIBLE_ANTHROPIC_API_KEY:` prompt, paste your key if it is not already exported. -4. At the `Other Anthropic-compatible endpoint model []:` prompt, enter the model ID exactly as it appears in your gateway's model catalog. - -**Option 6: Google Gemini:** - -Routes inference to Google's OpenAI-compatible Gemini endpoint at `https://generativelanguage.googleapis.com/v1beta/openai/`. - -Use `GEMINI_API_KEY` for the API key. Get one from [Google AI Studio API keys](https://aistudio.google.com/app/apikey). - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `6` to select **Google Gemini**. -2. At the `GEMINI_API_KEY:` prompt, paste your key if it is not already exported. -3. At the `Choose model [5]:` prompt, pick a curated model (for example, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, or `gemini-2.5-flash-lite`), or pick **Other...** to enter any Gemini model ID. - -**Option 7: Local Ollama:** - -Routes inference to a local Ollama instance. Depending on your platform, the wizard can use an existing daemon, start an installed daemon, or offer an install action. - -No API key is required. On non-WSL hosts, NemoClaw generates a token and starts an authenticated proxy so containers can reach Ollama without exposing the daemon directly to your network. -On WSL, NemoClaw can also use Ollama on the Windows host through `host.docker.internal`. - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `7` to select **Local Ollama**. -2. At the `Choose model [1]:` prompt, pick from **Ollama models** if any are already installed. If none are installed, pick a **starter model** to pull and load now, or pick **Other...** to enter any Ollama model ID. - -For setup details, including GPU recommendations and starter model choices, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). - -**Option 8: Model Router:** - -Starts a host-side model router and routes sandbox inference through OpenShell to that router. -The router chooses from the model pool in `nemoclaw-blueprint/router/pool-config.yaml` for each request. - -Use `NVIDIA_API_KEY` for the model pool credentials. - -Respond to the wizard as follows. - -1. At the `Choose [1]:` prompt, type `8` to select **Model Router (experimental)**. -2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. -3. Review the configuration summary and continue with the sandbox build. - -For scripted setup, set: - -```console -$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive -``` - -The router listens on the host at port `4000`. -The sandbox still calls `https://inference.local/v1`, so do not point in-sandbox tools at the host router port directly. - -**Local NIM and Local vLLM:** - -- **Local NVIDIA NIM** appears when `NEMOCLAW_EXPERIMENTAL=1` is set and the host has a NIM-capable GPU. NemoClaw pulls and manages a NIM container. -- **Local vLLM (already running)** appears whenever NemoClaw detects a vLLM server on `localhost:8000`. No flag is required for the menu entry. NemoClaw auto-detects the loaded model. -- **Local vLLM (managed install/start)** appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls and starts a vLLM container on supported hosts. - -For setup, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). diff --git a/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index dccb32a93c..4717cf5018 100644 --- a/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -3,12 +3,11 @@ Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent. The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected. -**Experimental Feature:** - -The Hermes agent option is experimental. -Interfaces, defaults, and supported features may change without notice, and it is not recommended for production use. - Review the [Prerequisites](prerequisites.md) before starting. +Install Docker, start it, and verify that the current shell can reach it before Hermes onboarding builds the sandbox image. +On Linux, the installer can install Docker, start the service, and add your user to the `docker` group. +If it changes group membership, run the printed `newgrp docker` recovery command before rerunning the installer. +On macOS, start Docker Desktop or Colima before you run the installer. The first Hermes build can take several minutes because NemoClaw builds the Hermes sandbox base image if it is not already cached. ## Install and Onboard @@ -16,20 +15,36 @@ The first Hermes build can take several minutes because NemoClaw builds the Herm Start the installer with `NEMOCLAW_AGENT=hermes` set in your shell. The installer installs the CLI, selects the `nemohermes` alias, and runs the guided onboarding flow. -```console -$ export NEMOCLAW_AGENT=hermes -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```bash +export NEMOCLAW_AGENT=hermes +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +If a headless host needs to expose the Hermes dashboard through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. +Use the externally reachable origin for the dashboard port `18789`. +NemoClaw derives the forwarded dashboard port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final dashboard URL in the ready summary. +The OpenAI-compatible API remains available separately on port `8642`. + +```bash +export NEMOCLAW_AGENT=hermes +export CHAT_UI_URL="https://hermes.example.com:18789" +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` +For SSH local port forwarding to `127.0.0.1:18789`, leave `CHAT_UI_URL` unset. +Do not append an OpenClaw `#token=` fragment to the Hermes dashboard URL. +Hermes API clients authenticate with the bearer token from the generated Hermes environment instead of an OpenClaw dashboard URL token. + If NemoClaw is already installed, start Hermes onboarding directly. -```console -$ nemohermes onboard +```bash +nemohermes onboard ``` ## Respond to the Wizard -The onboard wizard asks for a sandbox name, inference provider, model, credentials, and network policy preset. +The onboard wizard asks for an inference provider, model, any required credential, and sandbox name before it prints the review summary. +After you confirm, NemoClaw registers inference, prompts for supported messaging channels, builds and starts the sandbox, sets up Hermes, then applies the selected network policy tier and presets. At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. The default Hermes sandbox name is `hermes`. @@ -42,10 +57,10 @@ Sandbox name [hermes]: my-hermes Choose the inference provider that matches where you want Hermes model traffic to go. The provider options and credential environment variables are the same as the standard NemoClaw quickstart. -For provider-specific prompts, refer to the [Respond to the Onboard Wizard](../SKILL.md#respond-to-the-onboard-wizard) section and the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. +For provider-specific prompts, refer to the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. -After provider and policy selection, review the summary and confirm the build. +After provider and model selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. The Hermes image includes runtime dependencies for the supported NemoClaw messaging integrations, API service, and health endpoint. The base image does not include unsupported Hermes integrations. @@ -59,21 +74,24 @@ Hermes uses an agent-specific baseline policy that allows the Hermes binary and For CI or scripted installs, set the required environment variables before running the installer. The example below uses NVIDIA Endpoints and creates a sandbox named `my-hermes`. -```console -$ 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= -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```bash +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= +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` Use the provider variables from Inference Options (use the `nemoclaw-user-configure-inference` skill) when you choose a different provider. ## Connect to Hermes -When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes API endpoint. -Hermes exposes an OpenAI-compatible API on port `8642`, not a browser dashboard. +When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes dashboard 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 builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`. +Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text ────────────────────────────────────────────────── @@ -84,9 +102,9 @@ Model: nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) Access - Hermes Agent OpenAI-compatible API - Port 8642 must be forwarded before connecting. - http://127.0.0.1:8642/v1 + Hermes Agent Dashboard + Port 18789 must be forwarded before opening this URL. + http://127.0.0.1:18789/ Terminal: nemohermes my-hermes connect @@ -105,59 +123,74 @@ To chat with the agent from a terminal, follow these steps: 1. Connect to the sandbox and start the Hermes CLI. - ```console - $ nemohermes my-hermes connect + ```bash + nemohermes my-hermes connect ``` 2. Inside the sandbox, run the Hermes CLI. - ```console - $ hermes + ```bash + hermes ``` +## Open the Dashboard + +The onboard flow starts the dashboard port forward automatically. +Open the dashboard from the host: + +```console +$ nemohermes my-hermes dashboard-url --quiet +http://127.0.0.1:18789/ +``` + +Hermes handles dashboard sessions itself, so this URL does not include an OpenClaw `#token=` fragment. + ## Check the API Endpoint -The onboard flow starts the port forward automatically. +The onboard flow also starts the API port forward automatically. Check the health endpoint from the host to confirm that the Hermes API is reachable. -```console -$ curl -sf http://127.0.0.1:8642/health +```bash +curl -sf http://127.0.0.1:8642/health ``` If the command cannot connect after a reboot or terminal restart, start the forward again. -```console -$ openshell forward start --background 8642 my-hermes +```bash +openshell forward start --background 8642 my-hermes ``` Configure an OpenAI-compatible client with the base URL `http://127.0.0.1:8642/v1`. Hermes uses API header authentication for client requests. Do not append an OpenClaw `#token=` URL fragment to the Hermes endpoint. +Treat the dashboard as a local management UI. +Avoid exposing it on shared or public networks unless you put it behind your own access controls. + ## Manage the Sandbox Use the same lifecycle commands as a standard NemoClaw sandbox. The `nemohermes` alias keeps help text and recovery messages aligned with Hermes, while targeting the same registered sandbox. `nemoclaw list` shows the agent type for each sandbox so you can distinguish Hermes and OpenClaw entries. -```console -$ nemohermes my-hermes status -$ nemohermes my-hermes logs --follow -$ nemohermes my-hermes snapshot create --name before-change -$ nemohermes my-hermes rebuild +```bash +nemohermes my-hermes status +nemohermes my-hermes logs --follow +nemohermes my-hermes snapshot create --name before-change +nemohermes my-hermes rebuild ``` To change the active model or provider without rebuilding the sandbox, use `nemohermes inference set`. It updates the OpenShell inference route and patches `/sandbox/.hermes/config.yaml` without restarting Hermes. -```console -$ nemohermes inference set --model --provider +```bash +nemohermes inference set --model --provider ``` To remove the sandbox when you are done, destroy it explicitly. -```console -$ nemohermes my-hermes destroy +```bash +nemohermes my-hermes destroy ``` ## Next Steps diff --git a/skills/nemoclaw-user-get-started/references/windows-preparation.md b/skills/nemoclaw-user-get-started/references/windows-preparation.md index f3b87f30db..95e0eec6c5 100644 --- a/skills/nemoclaw-user-get-started/references/windows-preparation.md +++ b/skills/nemoclaw-user-get-started/references/windows-preparation.md @@ -1,19 +1,35 @@ # Prepare Windows for NemoClaw +import { AgentOnly } from "../_components/AgentGuide"; + You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. -Complete these steps before following the [Quickstart](../SKILL.md). + +Complete these steps before following the Quickstart. + + +Complete these steps before following Quickstart with Hermes. + Linux and macOS users do not need this page and can go directly to the Quickstart. **Note:** -This guide has been tested on x86-64. +NVIDIA tested this guide on x86-64. ## Prerequisites Verify the following before you begin: - Windows 10 (build 19041 or later) or Windows 11. -- Hardware requirements are the same as the [Quickstart](../SKILL.md). + + +- Hardware requirements are the same as the Quickstart. + + + + +- Hardware requirements are the same as Quickstart with Hermes. + + ## Option: Use the Bootstrap Script @@ -27,6 +43,8 @@ The command downloads the script to a temporary file before running it. `-ExecutionPolicy Bypass` applies only to that PowerShell process and avoids local policy blocking the downloaded script. Run it from Windows, not from inside WSL. The script requests Administrator privileges when needed, enables the required WSL 2 Windows features, installs or opens Ubuntu 24.04, and installs and starts Docker Desktop. +When Ubuntu needs first-run account setup, the script opens a handoff window and waits for that account to exist before it changes Docker settings. +It enables Docker Desktop WSL integration for the target distro, restarts Docker Desktop only when Docker was already running, and leaves your global default WSL distro unchanged. If the target Ubuntu distro is already registered, the script confirms it uses WSL 2, converts it from WSL 1 when needed, and verifies Docker is reachable from WSL. If Windows requires a reboot after enabling WSL features, the script prompts for the reboot and registers a one-time continuation for the next sign-in. If Docker Desktop shows first-run prompts, complete them and return to the PowerShell window. @@ -43,10 +61,11 @@ When Windows preparation is complete, it opens Ubuntu and prints the standard in curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -If the bootstrap script reports that Docker is not reachable from Ubuntu, open Docker Desktop Settings and confirm that WSL integration is enabled for Ubuntu (Settings > Resources > WSL integration), then rerun the script. +If the bootstrap script reports that Ubuntu cannot reach Docker, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for Ubuntu (**Settings** > **Resources** > **WSL integration**), make sure Docker Desktop is running, then rerun the script. If the bootstrap script reports that `winget.exe` is not available (common on Windows Server or stripped Windows installs), install **App Installer** from the Microsoft Store (which provides `winget`), or download and install Docker Desktop manually from [docker.com](https://www.docker.com/products/docker-desktop/). -Rerun the bootstrap script after Docker Desktop is installed; the script skips the install step once it detects Docker Desktop is present. +After you install Docker Desktop, rerun the bootstrap script. +The script skips the install step after it detects Docker Desktop. The manual steps below describe the same Windows preparation pieces and are useful when you need to verify or repair WSL, Ubuntu, or Docker Desktop by hand. @@ -76,9 +95,9 @@ Let the distribution launch and complete first-run setup (pick a Unix username a Do not use the `--no-launch` flag. The `--no-launch` flag downloads the package but does not register the distribution with WSL. -Commands like `wsl -d Ubuntu-24.04` fail with "There is no distribution with the supplied name" until the distribution has been launched at least once. +Commands like `wsl -d Ubuntu-24.04` fail with "There is no distribution with the supplied name" until you launch the distribution at least one time. -Verify the distribution is registered and running WSL 2: +Verify that WSL registered the distribution and runs it with WSL 2: ```powershell wsl -l -v @@ -95,7 +114,7 @@ Expected output: Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the WSL 2 backend (the default on Windows 11). -After installation, open Docker Desktop Settings and confirm that WSL integration is enabled for your Ubuntu distribution (Settings > Resources > WSL integration). +After installation, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for your Ubuntu distribution (**Settings** > **Resources** > **WSL integration**). Open WSL from PowerShell: @@ -110,7 +129,7 @@ docker info ``` `docker info` prints server information. -If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that WSL integration is enabled. +If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that Docker Desktop enables WSL integration. ## Set Up Local Inference with Ollama (Optional) @@ -121,7 +140,7 @@ You can install Ollama inside WSL yourself: curl -fsSL https://ollama.com/install.sh | sh ``` -If Ollama is installed but not already running in WSL, the onboarding process starts it for you. +If you installed Ollama but it is not already running in WSL, onboarding starts it for you. You can also start it yourself beforehand with `ollama serve`. You can also use Ollama for Windows. @@ -135,10 +154,15 @@ Use one instance, or move one of them to a different port before running `nemocl Your Windows environment is ready. If you used the bootstrap script, follow the installer command it printed inside Ubuntu. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandbox. + +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the Quickstart to install NemoClaw and launch your first sandbox. + + +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with Quickstart with Hermes to install NemoClaw and launch your first Hermes sandbox. + All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, refer to the Windows Subsystem for Linux section (use the `nemoclaw-user-reference` skill) in the Troubleshooting guide. +For Windows-specific troubleshooting, refer to the Windows Subsystem for Linux section in the Troubleshooting guide. diff --git a/skills/nemoclaw-user-manage-policy/SKILL.md b/skills/nemoclaw-user-manage-policy/SKILL.md index 298c672588..cb1e41036e 100644 --- a/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/skills/nemoclaw-user-manage-policy/SKILL.md @@ -4,13 +4,11 @@ description: "Adds, removes, or modifies allowed endpoints in the sandbox policy license: "Apache-2.0" --- - - - # Customize the Sandbox Network Policy ## Gotchas +- Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match. - Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. ## Prerequisites @@ -18,9 +16,11 @@ license: "Apache-2.0" - A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes. - The OpenShell CLI on your `PATH`. -Add, remove, or modify the endpoints that the sandbox is allowed to reach. +import { AgentOnly } from "../_components/AgentGuide"; + +Add, remove, or modify the endpoints the sandbox can reach. -The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). +The NemoClaw repository defines the sandbox policy in a declarative YAML file, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime. NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI. **Note:** @@ -30,18 +30,34 @@ Apply a custom NemoClaw preset with `nemoclaw policy-add --from-file`. Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime. See Agent cannot reach a host-side HTTP service (use the `nemoclaw-user-reference` skill). +**Warning:** + +Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match. +OpenShell still applies SSRF protection separately, so a request can be denied if the final address resolves to a loopback, private, link-local, or otherwise blocked internal range. +If a package installer or browser runtime download still fails with an SSRF-style denial after you add the public host, install that binary into the sandbox image at build time with `nemoclaw onboard --from` (use the `nemoclaw-user-reference` skill) instead of relying on runtime egress. + ## Static Changes Static changes modify the baseline policy file and take effect after the next sandbox creation. ### Edit the Policy File + Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `nemoclaw onboard`. If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit `openclaw-sandbox.yaml`. + + +Open the Hermes policy additions and shared sandbox policy files under `agents/hermes/` and `nemoclaw-blueprint/policies/`, then add or modify endpoint entries. + +If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `nemoclaw onboard`. + +If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). +That updates the live policy and does not edit the baseline policy files. + Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. @@ -60,18 +76,18 @@ Each entry in the `network` section defines an endpoint group with the following Apply the updated policy by re-running the onboard wizard: -```console -$ nemoclaw onboard +```bash +nemoclaw onboard ``` -The wizard picks up the modified policy file and applies it to the sandbox. +The wizard reads the modified policy file and applies it to the sandbox. ### Verify the Policy Check that the sandbox is running with the updated policy: -```console -$ nemoclaw status +```bash +nemoclaw status ``` ### Add Blueprint Policy Additions @@ -86,7 +102,7 @@ Dynamic changes apply a policy update to a running sandbox without restarting it > [!WARNING] > `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge. -> A running sandbox's live policy is the baseline from `openclaw-sandbox.yaml` plus every preset that was layered on during onboarding. +> A running sandbox's live policy is the baseline policy plus every preset that was layered on during onboarding. > Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect. ### Option 1: Drop a Preset File and Use `policy-add` (Recommended) @@ -116,41 +132,46 @@ This is the non-destructive path and the only flow NemoClaw supports out of the 2. Apply it to the running sandbox: - ```console - $ nemoclaw my-assistant policy-add - ``` +```bash +nemoclaw my-assistant policy-add +``` - NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. - Existing presets and the baseline remain in place. - The preset file under `presets/` also persists across sandbox recreations. +NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. +Existing presets and the baseline remain in place. +The preset file under `presets/` also persists across sandbox recreations. -### Option 2: Snapshot, Edit, and Set via OpenShell +### Option 2: Snapshot, Edit, and Set with OpenShell Use this path only when you cannot add a file under the NemoClaw source tree. -You must start from the **live** policy, not from `openclaw-sandbox.yaml`, so the presets layered on at onboarding are preserved in the file you apply. +You must start from the **live** policy, not from a baseline policy file, so the presets layered on at onboarding are preserved in the file you apply. -```console -$ openshell policy get --full my-assistant > live-policy.yaml +```bash +openshell policy get --full my-assistant > live-policy.yaml ``` Edit `live-policy.yaml` to add your entries under `network_policies:`, keeping the existing `version` field intact, then apply: -```console -$ openshell policy set --policy live-policy.yaml my-assistant +```bash +openshell policy set --policy live-policy.yaml my-assistant ``` ### Scope of Dynamic Changes Dynamic changes apply only to the current session. -When the sandbox stops, the running policy resets to the baseline composed from `openclaw-sandbox.yaml` 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`. +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`. + ### Approve Requests Interactively For one-off access, you can approve blocked requests in the OpenShell TUI instead of editing the baseline policy: -```console -$ openshell term +```bash +openshell term ``` This is useful when you want to test a destination before deciding whether it belongs in a permanent preset or custom policy file. @@ -186,8 +207,8 @@ Available presets: To apply a preset to a running sandbox: -```console -$ nemoclaw policy-add +```bash +nemoclaw policy-add ``` **Note:** @@ -197,29 +218,33 @@ Pass a preset name with `--yes` for scripted workflows. For example, to interactively add PyPI access to a running sandbox: -```console -$ nemoclaw my-assistant policy-add +```bash +nemoclaw my-assistant policy-add ``` To list which presets are applied to a sandbox: -```console -$ nemoclaw policy-list +```bash +nemoclaw policy-list ``` + To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. + + +To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemoclaw onboard`. + **Note:** -The `openshell policy set --policy ` command operates on raw policy files and does not -accept the `preset:` metadata block used in preset YAML files. Use `nemoclaw policy-add` for -presets. +The `openshell policy set --policy ` command operates on raw policy files and does not accept the `preset:` metadata block used in preset YAML files. +Use `nemoclaw policy-add` for presets. For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument: -```console -$ nemoclaw my-assistant policy-add pypi --yes -$ nemoclaw my-assistant policy-remove pypi --yes +```bash +nemoclaw my-assistant policy-add pypi --yes +nemoclaw my-assistant policy-remove pypi --yes ``` Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable. @@ -258,16 +283,16 @@ Rename `preset.name` if NemoClaw refuses to apply the file because of a collisio ### Apply a Single File -```console -$ nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml +```bash +nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. ### Apply Every File in a Directory -```console -$ nemoclaw my-assistant policy-add --from-dir ./presets/ --yes +```bash +nemoclaw my-assistant policy-add --from-dir ./presets/ --yes ``` Files are processed in lexicographic order. @@ -279,13 +304,21 @@ Fix the failing file and re-run the command to continue. Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. Review every host in a custom preset before applying it, especially when the file originates outside your team. -Load [references/customize-network-policy-details.md](references/customize-network-policy-details.md) for detailed steps on Remove a Custom Preset. +### Remove a Custom Preset + +NemoClaw records custom presets applied with `--from-file` or `--from-dir` in the sandbox registry alongside their full YAML content. +You can remove them by name without keeping the original file on disk: + +```bash +nemoclaw my-assistant policy-remove my-internal-api --yes +``` + +`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. ## References - **[references/integration-policy-examples.md](references/integration-policy-examples.md)** — Guides users through common post-install integration policy setup for maintained NemoClaw policy presets, including Outlook, messaging channels, GitHub, Jira, Brave Search, package managers, Hugging Face, local inference, and OpenShell approval workflows. - **Load [references/approve-network-requests.md](references/approve-network-requests.md)** when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI. Reviews and approves blocked agent network requests in the TUI. -- **Load [references/customize-network-policy-details.md](references/customize-network-policy-details.md)** when you need detailed steps for Remove a Custom Preset. ## Related Skills diff --git a/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md b/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md index bb1e73d494..6c97de9f7c 100644 --- a/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md +++ b/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md @@ -1,5 +1,3 @@ - - # Approve or Deny Agent Network Requests Review and act on network requests that the agent makes to endpoints not listed in the sandbox policy. @@ -14,14 +12,14 @@ OpenShell intercepts these requests and presents them in the TUI for operator ap Start the OpenShell terminal UI to monitor sandbox activity: -```console -$ openshell term +```bash +openshell term ``` For a remote sandbox, pass the instance name: -```console -$ ssh my-gpu-box 'cd ~/nemoclaw && . .env && openshell term' +```bash +ssh my-gpu-box 'cd ~/nemoclaw && . .env && openshell term' ``` The TUI displays the sandbox state, active inference provider, and a live feed of network activity. @@ -50,8 +48,8 @@ To keep an endpoint allowed after a restart, update the policy YAML or apply a p From the NemoClaw repository root, run the walkthrough script after you have onboarded at least one sandbox and it is reachable: -```console -$ ./scripts/walkthrough.sh +```bash +./scripts/walkthrough.sh ``` This script opens a split tmux session with the TUI on the left and the agent on the right. diff --git a/skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md b/skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md deleted file mode 100644 index 224829b964..0000000000 --- a/skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md +++ /dev/null @@ -1,13 +0,0 @@ - - -# Customize the Sandbox Network Policy: Details - -## Remove a Custom Preset - -Custom presets applied with `--from-file` or `--from-dir` are recorded in the NemoClaw sandbox registry alongside their full YAML content, so they can be removed by name — the original file does not need to be kept on disk: - -```console -$ nemoclaw my-assistant policy-remove my-internal-api --yes -``` - -`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. diff --git a/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md index db1c12d1db..18d77758ba 100644 --- a/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md +++ b/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -1,7 +1,7 @@ - - # Common NemoClaw Integration Policy Examples +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/`. Integration setup usually has two separate parts: @@ -18,19 +18,19 @@ Replace `my-assistant` with your sandbox name in the examples. Check the current policy state first: -```console -$ nemoclaw my-assistant policy-list +```bash +nemoclaw my-assistant policy-list ``` For a live view of blocked requests, open the OpenShell TUI in a separate host terminal: -```console -$ openshell term +```bash +openshell term ``` When the agent reaches an endpoint that is not in policy, the TUI shows the host, port, requesting binary, method, and path when available. Approve a request only when you understand why the integration needs it. -An approval updates the running policy, but it does not create a NemoClaw preset entry that can be reviewed and replayed like `policy-add`. +An approval updates the running policy, but it does not create a reviewable NemoClaw preset entry that `policy-add` can replay. ## Supported Integration Presets @@ -56,20 +56,20 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr Preview the endpoints before applying: -```console -$ nemoclaw my-assistant policy-add outlook --dry-run +```bash +nemoclaw my-assistant policy-add outlook --dry-run ``` Apply the preset: -```console -$ nemoclaw my-assistant policy-add outlook --yes +```bash +nemoclaw my-assistant policy-add outlook --yes ``` Remove it later if the sandbox no longer needs that access: -```console -$ nemoclaw my-assistant policy-remove outlook --yes +```bash +nemoclaw my-assistant policy-remove outlook --yes ``` ## Email and Calendar With Microsoft 365 @@ -77,9 +77,9 @@ $ nemoclaw my-assistant policy-remove outlook --yes Use the `outlook` preset for Microsoft 365 email and calendar workflows that use Microsoft Graph or Outlook endpoints. The preset allows `graph.microsoft.com`, Microsoft login, and Outlook service endpoints. -```console -$ nemoclaw my-assistant policy-add outlook --dry-run -$ nemoclaw my-assistant policy-add outlook --yes +```bash +nemoclaw my-assistant policy-add outlook --dry-run +nemoclaw my-assistant policy-add outlook --yes ``` Then configure the email or calendar tool credentials through the integration you are running in the sandbox. @@ -93,23 +93,23 @@ If the blocked endpoint is not covered by the maintained `outlook` preset, treat Telegram needs both channel configuration and egress policy. If you already enabled Telegram during onboarding but did not include the preset, add it to the running sandbox: -```console -$ nemoclaw my-assistant policy-add telegram --yes +```bash +nemoclaw my-assistant policy-add telegram --yes ``` To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and make sure the policy preset is applied: -```console -$ export TELEGRAM_BOT_TOKEN= -$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram -$ nemoclaw my-assistant rebuild -$ nemoclaw my-assistant policy-add telegram --yes +```bash +export TELEGRAM_BOT_TOKEN= +NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram +nemoclaw my-assistant rebuild +nemoclaw my-assistant policy-add telegram --yes ``` If delivery fails, open the TUI and send a test message to the bot: -```console -$ openshell term +```bash +openshell term ``` The matching preset for each supported messaging channel is the channel name (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`). @@ -121,60 +121,61 @@ Use the matching policy preset after you configure the channel credentials. For Slack: -```console -$ export SLACK_BOT_TOKEN= -$ export SLACK_APP_TOKEN= -$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack -$ nemoclaw my-assistant rebuild -$ nemoclaw my-assistant policy-add slack --yes +```bash +export SLACK_BOT_TOKEN= +export SLACK_APP_TOKEN= +NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack +nemoclaw my-assistant rebuild +nemoclaw my-assistant policy-add slack --yes ``` For Discord: -```console -$ export DISCORD_BOT_TOKEN= -$ export DISCORD_SERVER_ID= -$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord -$ nemoclaw my-assistant rebuild -$ nemoclaw my-assistant policy-add discord --yes +```bash +export DISCORD_BOT_TOKEN= +export DISCORD_SERVER_ID= +NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord +nemoclaw my-assistant rebuild +nemoclaw my-assistant policy-add discord --yes ``` If you enabled Slack or Discord during onboarding, apply only the matching preset: -```console -$ nemoclaw my-assistant policy-add slack --yes -$ nemoclaw my-assistant policy-add discord --yes +```bash +nemoclaw my-assistant policy-add slack --yes +nemoclaw my-assistant policy-add discord --yes ``` ## WeChat or WhatsApp Messaging (Experimental) WeChat and WhatsApp are experimental. -Both rely on QR-based pairing flows that are more fragile than token-based bots, and the upstream client libraries can change behavior without notice. +Both rely on QR-based pairing flows that are more fragile than token-based bots. +The upstream client libraries can change behavior without notice. WeChat uses Tencent's iLink Bot API for personal accounts. The bot token is captured by a host-side QR scan during onboarding rather than pasted from a developer portal. Add the channel interactively and apply the preset: -```console -$ nemoclaw my-assistant channels add wechat -$ nemoclaw my-assistant rebuild -$ nemoclaw my-assistant policy-add wechat --yes +```bash +nemoclaw my-assistant channels add wechat +nemoclaw my-assistant rebuild +nemoclaw my-assistant policy-add wechat --yes ``` -WhatsApp Web pairs entirely inside the sandbox via QR scan, so `channels add` does not collect a host-side token. +WhatsApp Web pairs entirely inside the sandbox through QR scan, so `channels add` does not collect a host-side token. Apply the preset and complete the in-sandbox pairing after the rebuild: -```console -$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp -$ nemoclaw my-assistant rebuild -$ nemoclaw my-assistant policy-add whatsapp --yes +```bash +NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp +nemoclaw my-assistant rebuild +nemoclaw my-assistant policy-add whatsapp --yes ``` If you enabled WeChat or WhatsApp during onboarding, apply only the matching preset: -```console -$ nemoclaw my-assistant policy-add wechat --yes -$ nemoclaw my-assistant policy-add whatsapp --yes +```bash +nemoclaw my-assistant policy-add wechat --yes +nemoclaw my-assistant policy-add whatsapp --yes ``` ## GitHub and Jira @@ -184,37 +185,38 @@ Use `jira` when the agent needs Atlassian Jira access. Preview first: -```console -$ nemoclaw my-assistant policy-add github --dry-run -$ nemoclaw my-assistant policy-add jira --dry-run +```bash +nemoclaw my-assistant policy-add github --dry-run +nemoclaw my-assistant policy-add jira --dry-run ``` Apply the preset that matches the workflow: -```console -$ nemoclaw my-assistant policy-add github --yes -$ nemoclaw my-assistant policy-add jira --yes +```bash +nemoclaw my-assistant policy-add github --yes +nemoclaw my-assistant policy-add jira --yes ``` The `jira` preset intentionally allows Node.js access to Atlassian Cloud and does not allow `curl`. When validating it manually, avoid plain `curl -s` against `auth.atlassian.com`. Atlassian can return an empty redirect body even when the request succeeds. -Use an explicit status probe instead: +Use a body-visible API probe instead: -```console -$ node -e "require('https').get('https://api.atlassian.com', r => console.log(r.statusCode))" -$ curl -sS -o /dev/null -w '%{http_code}' --max-time 10 https://auth.atlassian.com +```bash +node -e "require('https').get('https://api.atlassian.com', r => console.log(r.statusCode))" +curl -sS --max-time 10 -w '\n%{http_code}\n' https://api.atlassian.com/oauth/token/accessible-resources ``` Before approval, the curl probe should report `000` or a local policy denial. -After approving the blocked request in OpenShell, it should report an HTTP -status such as `301` or `200`. +After explicitly approving curl for `api.atlassian.com` in OpenShell, it should return Atlassian's unauthenticated `401` JSON response. +That `401` is the expected success signal for this manual probe. +This manual probe proves curl reached Atlassian, but no Jira credentials were supplied. Remove access when the task is done: -```console -$ nemoclaw my-assistant policy-remove github --yes -$ nemoclaw my-assistant policy-remove jira --yes +```bash +nemoclaw my-assistant policy-remove github --yes +nemoclaw my-assistant policy-remove jira --yes ``` ## Brave Search @@ -222,9 +224,9 @@ $ nemoclaw my-assistant policy-remove jira --yes The default Balanced policy tier includes `brave`. If you chose Restricted during onboarding or removed the preset later, add it before enabling Brave Search workflows: -```console -$ nemoclaw my-assistant policy-add brave --dry-run -$ nemoclaw my-assistant policy-add brave --yes +```bash +nemoclaw my-assistant policy-add brave --dry-run +nemoclaw my-assistant policy-add brave --yes ``` The Brave Search API key is still configured separately during onboarding or through the web search setup flow. @@ -236,43 +238,50 @@ Use these presets when an agent workflow installs packages or downloads model as | Workflow | Preset | |----------|--------| | npm or Yarn packages | `npm` | -| Python packages from PyPI | `pypi` | +| Python packages from PyPI with `pip`, Python, or `uv` | `pypi` | | Homebrew packages | `brew` | | Hugging Face model or dataset access | `huggingface` | Add only the preset required for the task: -```console -$ nemoclaw my-assistant policy-add npm --yes -$ nemoclaw my-assistant policy-add pypi --yes -$ nemoclaw my-assistant policy-add brew --yes -$ nemoclaw my-assistant policy-add huggingface --yes +```bash +nemoclaw my-assistant policy-add npm --yes +nemoclaw my-assistant policy-add pypi --yes +nemoclaw my-assistant policy-add brew --yes +nemoclaw my-assistant policy-add huggingface --yes ``` Remove package access after a one-time setup task if the sandbox no longer needs it: -```console -$ nemoclaw my-assistant policy-remove npm --yes -$ nemoclaw my-assistant policy-remove pypi --yes -$ nemoclaw my-assistant policy-remove brew --yes -$ nemoclaw my-assistant policy-remove huggingface --yes +```bash +nemoclaw my-assistant policy-remove npm --yes +nemoclaw my-assistant policy-remove pypi --yes +nemoclaw my-assistant policy-remove brew --yes +nemoclaw my-assistant policy-remove huggingface --yes ``` +The `pypi` preset allows Python, `pip`, virtual-environment Python and `pip`, and `/usr/local/bin/uv` to reach PyPI endpoints. +If `uv` is installed somewhere else in the sandbox, add a custom preset for that binary path instead of broadening the maintained preset locally. + ### Homebrew Specifics The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` preset is the only step needed before installing a formula. -A `/usr/local/bin/brew` symlink puts the entry point on the sandbox `PATH`, so the agent can run `brew install ` directly: +A `/usr/local/bin/brew` wrapper puts the entry point on the sandbox `PATH` while delegating to the Linuxbrew prefix. +Installed formula commands are available from the Linuxbrew bin directory in sandbox shell sessions: -```console -$ nemoclaw my-assistant policy-add brew --yes -$ nemoclaw my-assistant exec -- brew install +```bash +nemoclaw my-assistant policy-add brew --yes +nemoclaw my-assistant exec -- brew install +nemoclaw my-assistant exec -- bash -lc '' ``` You do not need to bootstrap Homebrew, install build dependencies, or source `brew shellenv` inside the sandbox. ## Model Pricing -OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter on every start so it can populate `usage.cost` in session JSONL records. + + +OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter on every start to populate `usage.cost` in session JSONL records. The default-strict egress policy denies both hosts. The fetch fails closed, the gateway logs `[gateway/model-pricing] LiteLLM pricing fetch failed: TypeError: fetch failed` (and the matching OpenRouter line) on every startup, and every session record records `usage.cost = 0` even though the input and output token counts populate correctly. Tools that read the session log to display per-turn cost (audit dashboards, compliance review surfaces) cannot distinguish a real free run from this silent failure. @@ -280,12 +289,19 @@ Tools that read the session log to display per-turn cost (audit dashboards, comp Apply the `openclaw-pricing` preset to allow both pricing endpoints. The preset pins each host to a single read-only path so it does not widen egress beyond the pricing fetch: -```console -$ nemoclaw my-assistant policy-add openclaw-pricing --dry-run -$ nemoclaw my-assistant policy-add openclaw-pricing --yes +```bash +nemoclaw my-assistant policy-add openclaw-pricing --dry-run +nemoclaw my-assistant policy-add openclaw-pricing --yes ``` -After the next gateway restart the WARN entries stop and `usage.cost` populates from the fetched pricing tables. +After the next gateway restart, the WARN entries stop and `usage.cost` populates from the fetched pricing tables. + + + + +Hermes does not use OpenClaw's model-pricing reference fetch. + + ## Local Inference @@ -293,35 +309,35 @@ Use `local-inference` when the sandbox needs access to host-side local inference Onboarding auto-suggests this preset when you choose a local provider. If you need to add it after onboarding: -```console -$ nemoclaw my-assistant policy-add local-inference --dry-run -$ nemoclaw my-assistant policy-add local-inference --yes +```bash +nemoclaw my-assistant policy-add local-inference --dry-run +nemoclaw my-assistant policy-add local-inference --yes ``` Then verify the sandbox status: -```console -$ nemoclaw my-assistant status +```bash +nemoclaw my-assistant status ``` ## Inspect or Replace the Live Policy Use `policy-list` for normal preset state: -```console -$ nemoclaw my-assistant policy-list +```bash +nemoclaw my-assistant policy-list ``` Use OpenShell when you need the full enforced YAML: -```console -$ openshell policy get --full my-assistant > live-policy.yaml +```bash +openshell policy get --full my-assistant > live-policy.yaml ``` If you must replace the live policy, edit the full policy file and set it back: -```console -$ openshell policy set --policy live-policy.yaml my-assistant --wait +```bash +openshell policy set --policy live-policy.yaml my-assistant --wait ``` `openshell policy set` replaces the live policy with the file you provide. diff --git a/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/skills/nemoclaw-user-manage-sandboxes/SKILL.md index b5618052c5..9cb897f094 100644 --- a/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -1,75 +1,89 @@ --- name: "nemoclaw-user-manage-sandboxes" -description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." +description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemohermes dockerignore, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." license: "Apache-2.0" --- - - - # Manage Sandbox Lifecycle +import { AgentOnly } from "../_components/AgentGuide"; + + Use this guide after you finish the OpenClaw quickstart (use the `nemoclaw-user-get-started` skill). + + +Use this guide after you finish Quickstart with Hermes (use the `nemoclaw-user-get-started` skill). + It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. + When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw` and `openshell`. + + +When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw`, `nemoclaw`, and `openshell`. + ## List Sandboxes List every sandbox registered on this host: -```console -$ nemoclaw list +```bash +nemoclaw list ``` -The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when a dashboard port is recorded. +The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when NemoClaw records a dashboard port. Use JSON output for scripts: -```console -$ nemoclaw list --json +```bash +nemoclaw list --json ``` ## Check Sandbox Health Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings: -```console -$ nemoclaw my-assistant status +```bash +nemoclaw my-assistant status ``` Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared: -```console -$ nemoclaw status +```bash +nemoclaw status ``` ## Inspect Logs View recent sandbox logs: -```console -$ nemoclaw my-assistant logs +```bash +nemoclaw my-assistant logs ``` Stream logs while you reproduce a problem: -```console -$ nemoclaw my-assistant logs --follow +```bash +nemoclaw my-assistant logs --follow ``` + The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs. + + +The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs. + ## Collect Diagnostics Collect diagnostics for bug reports or support handoff: -```console -$ nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz +```bash +nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` Use `--quick` for a smaller local summary: -```console -$ nemoclaw debug --quick --sandbox my-assistant +```bash +nemoclaw debug --quick --sandbox my-assistant ``` The debug command gathers system information, Docker state, gateway logs, and sandbox status. @@ -78,37 +92,44 @@ The debug command gathers system information, Docker state, gateway logs, and sa If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart it manually with the port from the install summary. -```console -$ openshell forward start --background my-gpt-claw +```bash +openshell forward start --background my-gpt-claw ``` To list active forwards across all sandboxes, run the following command. -```console -$ openshell forward list +```bash +openshell forward list ``` ## Run Multiple Sandboxes Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. + When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. + + +When the default API port is already held by another sandbox, `nemoclaw onboard` scans for the next free port and records it for the sandbox. + +If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. +NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. -```console -$ nemoclaw onboard # first sandbox uses 18789 -$ nemoclaw onboard # second sandbox uses the next free port, such as 18790 +```bash +nemoclaw onboard # first sandbox uses 18789 +nemoclaw onboard # second sandbox uses the next free port, such as 18790 ``` To choose a specific port, pass `--control-ui-port`: -```console -$ nemoclaw onboard --control-ui-port 19000 +```bash +nemoclaw onboard --control-ui-port 19000 ``` You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding: -```console -$ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard -$ NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard +```bash +CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard +NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard ``` For full details on port conflicts and overrides, refer to Port already in use (use the `nemoclaw-user-reference` skill). @@ -121,18 +142,23 @@ Recover from a misconfigured sandbox without re-running the full onboard wizard Change the active model or provider at runtime without rebuilding the sandbox: -```console -$ nemoclaw inference set --model --provider +```bash +nemoclaw inference set --model --provider ``` Refer to Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward + If `nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. + + +If `nemoclaw status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. + -```console -$ nemoclaw recover +```bash +nemoclaw recover ``` The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step. @@ -141,22 +167,27 @@ Refer to `nemoclaw recover` (use the `nemoclaw-user-reference` skill) for ### Reset a Stored Credential -If a provider credential was entered incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: +If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: -```console -$ nemoclaw credentials list # see which providers are registered -$ nemoclaw credentials reset # clear a single provider, for example nvidia-prod -$ nemoclaw onboard # re-run to re-enter the cleared provider +```bash +nemoclaw credentials list # see which providers are registered +nemoclaw credentials reset # clear a single provider, for example nvidia-prod +nemoclaw onboard # re-run to re-enter the cleared provider ``` -The credentials command is documented in full at `nemoclaw credentials reset ` (use the `nemoclaw-user-reference` skill). +The command reference documents `nemoclaw credentials reset ` (use the `nemoclaw-user-reference` skill) in full. ### Rebuild a Sandbox While Preserving Workspace State + If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating: + + +If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox's state files, use `rebuild` instead of destroying and recreating: + -```console -$ nemoclaw rebuild +```bash +nemoclaw rebuild ``` Rebuild preserves the mounted workspace and registered policies while recreating the container. @@ -167,8 +198,8 @@ Refer to `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill) for Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding: -```console -$ nemoclaw policy-add +```bash +nemoclaw policy-add ``` Refer to `nemoclaw policy-add` (use the `nemoclaw-user-reference` skill) for usage details and flags. @@ -177,48 +208,30 @@ Non-interactive re-onboards in the default `suggested` policy mode preserve pres To make a re-onboard authoritative, set `NEMOCLAW_POLICY_MODE=custom` and provide `NEMOCLAW_POLICY_PRESETS` with the exact list to apply; onboarding removes anything else. See `NEMOCLAW_POLICY_MODE` (use the `nemoclaw-user-reference` skill) for the full table. -## Update to the Latest Version - -When a new NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions. - -### Update the NemoClaw CLI - -Re-run the installer. -Before it onboards anything, the installer calls `nemoclaw backup-all` (use the `nemoclaw-user-reference` skill) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. -If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path. -The automatic path is offered only when the existing `nemoclaw` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway. -For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all` and `openshell gateway destroy -g nemoclaw || openshell gateway destroy` before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. - -```console -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -``` - -### Upgrade Sandboxes with Stale Agent and Runtime Versions +## Update to the Maintained Version -The installer checks registered sandboxes after onboarding succeeds and runs `nemoclaw upgrade-sandboxes --auto` for stale running sandboxes. -Use `upgrade-sandboxes` directly to verify the result, rebuild when you skipped the installer or onboarding step, or handle sandboxes that were stopped or could not be version-checked. -The upgrade flow is non-destructive by default because NemoClaw preserves manifest-defined workspace state, but a manual snapshot before any major upgrade gives you a state restore point. +When a maintained NemoClaw release becomes available, update the host CLI and then check whether existing sandboxes need rebuilds. +The standard installer follows the admin-promoted `lkg` release tag by default. +If you need a specific release, set `NEMOCLAW_INSTALL_TAG` on the `bash` side of the install pipeline. -```console -$ nemoclaw snapshot create --name pre-upgrade # optional, recommended -$ nemoclaw update --yes # updates CLI through the maintained installer flow -$ nemoclaw upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes -$ nemoclaw upgrade-sandboxes # manually rebuild remaining stale running sandboxes +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=v0.0.56 bash +nemoclaw upgrade-sandboxes --check ``` -`nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. -Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. - -For scripted manual rebuilds, use `nemoclaw upgrade-sandboxes --auto` to skip the confirmation prompt. +Before upgrade work, the installer runs `nemoclaw backup-all` when the installed CLI supports it. +For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need: -If the upgraded sandbox needs its workspace state reverted, restore the pre-upgrade snapshot into the running sandbox. -This restores saved state directories only; it does not downgrade the sandbox image or agent/runtime: - -```console -$ nemoclaw snapshot restore pre-upgrade +```bash +nemoclaw snapshot create --name pre-upgrade +nemoclaw update --yes +nemoclaw upgrade-sandboxes --check ``` -Load [references/lifecycle-details.md](references/lifecycle-details.md) for detailed steps on What Changes During a Rebuild. +Each rebuild destroys the old container and creates a new one, while preserving the manifest-defined workspace or agent state that NemoClaw knows how to snapshot. +Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved. +For the full state-preservation contract, snapshot restore behavior, and manual backup workflow, refer to [Backup and Restore](references/backup-restore.md). +For command flags, refer to `nemoclaw update` (use the `nemoclaw-user-reference` skill), `nemoclaw upgrade-sandboxes` (use the `nemoclaw-user-reference` skill), and `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill). ## Uninstall @@ -234,9 +247,17 @@ nemoclaw uninstall | `--keep-openshell` | Leave OpenShell binaries installed. | | `--delete-models` | Also remove NemoClaw-pulled Ollama models. | -`nemoclaw uninstall` runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. +**Note:** + +The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots that snapshot and `backup-all` commands write), `~/.nemoclaw/backups/` (workspace backups that `scripts/backup-workspace.sh` writes), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default. +Uninstall removes every other entry under `~/.nemoclaw/`. +Interactive runs prompt before they remove the preserved entries; the default answer keeps them. +For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well. +See the Commands reference (use the `nemoclaw-user-reference` skill) for the full preservation contract. + +The CLI uninstall command runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. -If the `nemoclaw` CLI is missing or broken, fall back to the hosted script: +If the CLI is missing or broken, fall back to the hosted script: ```bash curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash @@ -248,15 +269,15 @@ The same `--yes`, `--keep-openshell`, and `--delete-models` flags listed above a curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes --delete-models ``` -For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, see `nemoclaw uninstall` vs. the hosted `uninstall.sh` (use the `nemoclaw-user-reference` skill). +For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, refer to `nemoclaw uninstall` vs. the hosted `uninstall.sh` (use the `nemoclaw-user-reference` skill). ## References - **[references/runtime-controls.md](references/runtime-controls.md)** — Single page that answers what can change at runtime versus what requires a rebuild for NemoClaw sandboxes. - **Load [references/backup-restore.md](references/backup-restore.md)** when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds. Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds. - **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, WeChat, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands. +- **Load [references/install-plugins-hermes.md](references/install-plugins-hermes.md)** when users ask how to install, build, or configure Hermes plugins under NemoClaw. Explains how to install Hermes plugins in NemoClaw-managed sandboxes, including custom Dockerfile build-directory layout and `.dockerignore` handling. - **Load [references/workspace-files.md](references/workspace-files.md)** when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state. Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts. -- **Load [references/lifecycle-details.md](references/lifecycle-details.md)** when you need detailed steps for What Changes During a Rebuild. ## Related Skills diff --git a/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md b/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md index 70da806410..ccebd8b589 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md @@ -1,103 +1,157 @@ - - # Backup and Restore Workspace Files -Workspace files define your agent's personality, memory, and user context. -They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. +import { AgentOnly } from "../_components/AgentGuide"; + +Workspace and state files define your agent's personality, memory, user context, and durable runtime state. +They persist across sandbox restarts but are **permanently deleted** when you destroy the sandbox. This guide covers snapshot commands, manual backup with CLI commands, and an automated script. ## When to Back Up -- **Before running `nemoclaw destroy`** + + +- Before running `nemoclaw destroy` - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent + + + +- Before running `nemoclaw destroy` +- Before major NemoClaw version upgrades +- Periodically, if you've invested time customizing your agent or paired messaging channels + + + ## Snapshot Commands The fastest way to back up and restore sandbox state is with the built-in snapshot commands. Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups//`. -Agent manifests may 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. - -```console -$ nemoclaw my-assistant snapshot create -$ nemoclaw my-assistant snapshot list -$ nemoclaw my-assistant snapshot restore +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. + +```bash +nemoclaw my-assistant snapshot create +nemoclaw my-assistant snapshot list +nemoclaw my-assistant snapshot restore ``` -`snapshot list` prints a table of version, name, timestamp, and path. Versions (`v1`, `v2`, ..., `vN`) are computed from the timestamp order, so `vN` is always the newest snapshot. +`snapshot list` prints a table of version, name, timestamp, and path. +NemoClaw computes versions (`v1`, `v2`, ..., `vN`) from timestamp order, so `vN` is always the newest snapshot. To tag a snapshot with a human-readable label, pass `--name`: -```console -$ nemoclaw my-assistant snapshot create --name before-upgrade +```bash +nemoclaw my-assistant snapshot create --name before-upgrade ``` To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix: -```console -$ nemoclaw my-assistant snapshot restore v3 -$ nemoclaw my-assistant snapshot restore before-upgrade -$ nemoclaw my-assistant snapshot restore 2026-04-14T +```bash +nemoclaw my-assistant snapshot restore v3 +nemoclaw my-assistant snapshot restore before-upgrade +nemoclaw my-assistant snapshot restore 2026-04-14T ``` To clone a snapshot into a different sandbox name, pass `--to `. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`: -```console -$ nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone -$ nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes +```bash +nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone +nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes ``` + + +The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. +Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that older images created. +NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. + + + + The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. -Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that were created by older images. -Unsafe symlinks and hard links inside sandbox state are rejected during backup creation before they can enter a snapshot. +NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. Credential-bearing Hermes files such as `auth.json` are intentionally excluded from snapshots. NemoClaw-regenerated Hermes config files (`config.yaml` and `.env`) are also excluded; model/provider and messaging credentials are recreated from host-side onboarding and OpenShell provider state during rebuild. + + For full details, see the Commands reference (use the `nemoclaw-user-reference` skill). ## Manual Backup Use `openshell sandbox download` to copy files from the sandbox to your host. -```console -$ SANDBOX=my-assistant -$ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) -$ mkdir -p "$BACKUP_DIR" - -$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/" -$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/" -$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/" -$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/" -$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/" -$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" + + +```bash +SANDBOX=my-assistant +BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +mkdir -p "$BACKUP_DIR" + +openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" ``` + + + +```bash +SANDBOX=my-hermes +BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +mkdir -p "$BACKUP_DIR" + +openshell sandbox download "$SANDBOX" /sandbox/SOUL.md "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.hermes/state.db "$BACKUP_DIR/" +openshell sandbox download "$SANDBOX" /sandbox/.hermes/platforms/ "$BACKUP_DIR/platforms/" +``` + + + ## Manual Restore Use `openshell sandbox upload` to push files back into a sandbox. -```console -$ SANDBOX=my-assistant -$ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp - -$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ -$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/ -$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/ -$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/ -$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/ -$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ + + +```bash +SANDBOX=my-assistant +BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ ``` + + + +```bash +SANDBOX=my-hermes +BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/state.db" /sandbox/.hermes/ +openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/platforms/ +``` + + + ## Using the Backup Script + + The repository includes a convenience script at `scripts/backup-workspace.sh`. ### Backup @@ -112,14 +166,14 @@ Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ (6 items) Restore from the most recent backup: -```console -$ ./scripts/backup-workspace.sh restore my-assistant +```bash +./scripts/backup-workspace.sh restore my-assistant ``` Restore from a specific timestamp: -```console -$ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000 +```bash +./scripts/backup-workspace.sh restore my-assistant 20260320-120000 ``` ## Verifying a Backup @@ -136,31 +190,47 @@ USER.md memory/ ``` + + + +For Hermes, prefer the built-in snapshot commands for faithful restore of `state.db`. +Use manual `openshell sandbox download` / `openshell sandbox upload` only when you need to inspect or transfer a specific file. + + + + + ## Multi-Agent Deployments -When OpenClaw is configured with multiple named agents, each agent has its own -workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, -and so on — see [Multi-Agent Deployments](workspace-files.md#multi-agent-deployments)). +When you configure OpenClaw with multiple named agents, each agent has its own workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, and so on). +Refer to [Multi-Agent Deployments](workspace-files.md#multi-agent-deployments). -`nemoclaw snapshot create` automatically discovers every `workspace-*/` -directory under the sandbox state tree and includes it in the snapshot bundle -alongside the default `workspace/`. `snapshot restore` re-applies the full -per-agent set. No manual per-workspace backup pattern is needed. +`nemoclaw snapshot create` automatically discovers every `workspace-*/` directory under the sandbox state tree and includes it in the snapshot bundle alongside the default `workspace/`. +`snapshot restore` reapplies the full per-agent set. +You do not need a manual per-workspace backup pattern. -The sandbox entrypoint ensures every per-agent workspace lives directly under -the persistent `.openclaw/` tree, so state also survives `openshell sandbox restart`. +The sandbox entrypoint ensures every per-agent workspace lives directly under the persistent `.openclaw/` tree, so state also survives `openshell sandbox restart`. ### Shared files across agents Files that operators typically want consistent across every per-agent workspace (`AGENTS.md`, shared skills, common templates) are **not** synced automatically. -Each workspace is independent; changes in one don't propagate. Operators that -need this either copy the shared files explicitly to each workspace after -editing, or maintain a host-side sync layer. Tracking shared-file tooling -(shared mount, `workspaces list` command) in -[#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). +Each workspace is independent, and changes in one do not propagate. +Operators that need this either copy the shared files explicitly to each workspace after editing or maintain a host-side sync layer. +NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). + + + + +## Hermes State + +Hermes does not use OpenClaw per-agent workspace directories. +NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable top-level files instead. +Refer to [Workspace Files](workspace-files.md) for the Hermes state layout. + + ## Next Steps -- [Workspace Files overview](workspace-files.md) to learn what each file does +- [Workspace Files overview](workspace-files.md) to learn what each file does. - Commands reference (use the `nemoclaw-user-reference` skill) diff --git a/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md b/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md new file mode 100644 index 0000000000..4e3deaab2c --- /dev/null +++ b/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md @@ -0,0 +1,117 @@ +# Install Hermes Plugins + +Hermes plugins extend the Hermes runtime inside a NemoClaw-managed sandbox. +They are different from NemoClaw skills and from OpenClaw plugins, so install them through the Hermes plugin path instead of `skill install`. + +## How Hermes Loads Plugins + +NemoClaw sets `HERMES_HOME` to `/sandbox/.hermes` when it starts the Hermes gateway. +Hermes plugin directories live under `/sandbox/.hermes/plugins/`. +NemoClaw uses the same mechanism for its built-in Hermes integration, which the sandbox image bakes into `/sandbox/.hermes/plugins/nemoclaw`. + +The built-in NemoClaw Hermes plugin provides sandbox status tools, skill reload support, managed-tool broker patches, and runtime grounding for the OpenShell sandbox. +Do not replace or remove `/sandbox/.hermes/plugins/nemoclaw` when you add your own plugin. + +## Choose an Install Path + +Today, the supported path for custom Hermes plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. +Use this path when the plugin adds Python code, runtime hooks, or dependencies that Hermes must see at gateway startup. + +`nemohermes skill install ` is only for `SKILL.md` agent skills. +It uploads skill instructions and refreshes skill discovery, but it does not install Hermes runtime plugins. + +## Prepare a Build Directory + +Put the custom Dockerfile and everything it needs to `COPY` in one directory. +`nemohermes onboard --from ` sends the Dockerfile's parent directory as the Docker build context. +Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context. +NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them. + +```text +my-hermes-plugin-sandbox/ +├── Dockerfile +└── my-hermes-plugin/ + ├── __init__.py + └── requirements.txt +``` + +If you start from the stock NemoClaw Hermes Dockerfile, keep the NemoClaw Hermes image contract intact. +The image must still include the generated Hermes config, NemoClaw Hermes plugin, blueprint files, and `nemoclaw-start` entrypoint. + +**Warning:** + +A custom `--from` Dockerfile replaces the normal NemoClaw Hermes Dockerfile. + Starting from `ghcr.io/nvidia/nemoclaw/hermes-sandbox-base:latest` alone is not enough unless your Dockerfile also preserves the NemoClaw Hermes layers from `agents/hermes/Dockerfile`. + +## Install the Plugin in the Image + +Add your plugin after the Dockerfile has created `/sandbox/.hermes`. +The example below shows the layer that copies a plugin directory into the Hermes plugin tree. + +```dockerfile +COPY my-hermes-plugin/ /opt/my-hermes-plugin/ + +USER root +RUN mkdir -p /sandbox/.hermes/plugins/my-hermes-plugin \ + && cp -a /opt/my-hermes-plugin/. /sandbox/.hermes/plugins/my-hermes-plugin/ \ + && if [ -f /opt/my-hermes-plugin/requirements.txt ]; then \ + /opt/hermes/.venv/bin/python -m pip install --no-cache-dir -r /opt/my-hermes-plugin/requirements.txt; \ + fi \ + && chown -R sandbox:sandbox /sandbox/.hermes/plugins/my-hermes-plugin \ + && chmod -R a+rX /sandbox/.hermes/plugins/my-hermes-plugin + +USER sandbox +WORKDIR /sandbox +``` + +Keep plugin code and dependency files inside the build directory. +Avoid copying host credentials, local caches, or broad home-directory contents into the image. + +## Create the Sandbox + +Run onboarding with the custom Dockerfile and an explicit sandbox name. +NemoClaw requires a name for `--from` builds so a custom image cannot silently replace the default sandbox. + +```bash +nemohermes onboard --name my-hermes-build --from ./my-hermes-plugin-sandbox/Dockerfile +``` + +For non-interactive onboarding, set the same values through environment variables. + +```bash +NEMOCLAW_NON_INTERACTIVE=1 \ +NEMOCLAW_SANDBOX_NAME=my-hermes-build \ +NEMOCLAW_FROM_DOCKERFILE=./my-hermes-plugin-sandbox/Dockerfile \ +nemohermes onboard +``` + +If you resume an interrupted onboarding run, use the same Dockerfile path that started the session. +NemoClaw records the custom Dockerfile path and rejects a resume that points at a different image source. + +## Network Access + +Hermes plugins still run inside the OpenShell sandbox boundary. +If a plugin calls an external API at runtime, add a policy preset for the required hostnames and binaries before you recreate the sandbox. + +Hermes uses Python for plugin execution, so policy entries usually need to allow the Hermes Python runtime, such as `/opt/hermes/.venv/bin/python`, in addition to any command-line wrapper your plugin starts. +For package downloads during sandbox runtime, use the `pypi` preset or a custom preset that allows the package hosts you need. + +For policy concepts, refer to Network Policies (use the `nemoclaw-user-reference` skill). +For custom preset workflows, refer to Customize Network Policy (use the `nemoclaw-user-manage-policy` skill). + +## Common Mistakes + +These are the most common places where Hermes plugin installation gets mixed up with other NemoClaw extension paths. + +- Do not use `skill install` for Hermes runtime plugins. +- Do not install Hermes plugins into `/sandbox/.openclaw/extensions`; that path is for OpenClaw plugins. +- Do not remove `/sandbox/.hermes/plugins/nemoclaw`; NemoClaw depends on that plugin for managed Hermes behavior. +- Do not put the Dockerfile in a broad directory unless you intend to send that whole directory as the Docker build context. +- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. +- Do not assume OpenShell policy allows Python package downloads during runtime by default. + +## Next Steps + +- Review NemoHermes Command Reference (use the `nemoclaw-user-reference` skill) for `nemohermes onboard --from` details. +- Review Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) if the plugin needs runtime network egress. +- Review [Runtime Controls](runtime-controls.md) before changing shields or mutability settings for a plugin-enabled sandbox. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md b/skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md deleted file mode 100644 index 38d055b82f..0000000000 --- a/skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md +++ /dev/null @@ -1,26 +0,0 @@ - - -# Manage Sandbox Lifecycle: Details - -## What Changes During a Rebuild - -Each rebuild destroys the existing container and creates a new one. -NemoClaw protects your data through the same backup-and-restore flow as `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill): - -- NemoClaw preserves manifest-defined workspace state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the agent manifest, typically `/sandbox/.openclaw/workspace/`; for Hermes this also includes `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. -- NemoClaw does not preserve runtime changes outside the workspace state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-workspace paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. - -Aborts before the destroy step are non-destructive. -The flow refuses to proceed past preflight if a credential is missing or past backup if required manifest-defined state cannot be copied, so a failed run leaves the original sandbox intact and ready to retry. -When a backup command reports partial archive output, NemoClaw keeps the usable entries and reports only the manifest-defined paths that could not be archived. - -See [Backup and Restore](backup-restore.md) for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough. - -**If the rebuild aborts with `Missing credential: `:** - -The rebuild preflight reads the provider credential recorded by your last `nemoclaw onboard` session. -If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight may still reference the old key and fail before any destroy step runs. - -To recover, re-run `nemoclaw onboard` and select your current provider. -This refreshes the session metadata. -Your existing container keeps serving traffic until the new image is ready. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md b/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md index 7bbedeb592..978fd2fc2b 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md @@ -1,24 +1,36 @@ - - # Messaging Channels +import { AgentOnly } from "../_components/AgentGuide"; + Telegram, Discord, Slack, WeChat, and WhatsApp reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs. For token-based channels, NemoClaw registers credentials with OpenShell providers. WeChat captures a token through a host-side QR scan during onboarding. -WhatsApp pairs inside the sandbox via QR scan and intentionally stores mutable session state there. +WhatsApp pairs inside the sandbox through a QR scan and intentionally stores mutable session state there. NemoClaw bakes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control. **Experimental Channels:** WeChat and WhatsApp are experimental. Both rely on QR-based pairing flows that are more fragile than token-based bots, and the upstream client libraries can change behavior without notice. -Interfaces, defaults, and supported features may change, and these channels are not recommended for production use. +Interfaces, defaults, and supported features can change, and NVIDIA does not recommend these channels for production use. + +You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw channels` commands. +Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` at image build time, and changes inside the running container do not persist across rebuilds. + + You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw channels` commands. -Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes at image build time, and changes inside the running container do not persist across rebuilds. +Do not mutate messaging configuration directly inside the sandbox because NemoClaw generates `/sandbox/.hermes/.env` and Hermes config at image build time, and changes inside the running container do not persist across rebuilds. + + `nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) + + +`nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. +It only starts optional host services such as the cloudflared tunnel when that binary is present. + For details, refer to Commands (use the `nemoclaw-user-reference` skill). ## Prerequisites @@ -34,8 +46,8 @@ For details, refer to Commands (use the `nemoclaw-user-reference` skill). | Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | | Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` | | Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting, `SLACK_ALLOWED_CHANNELS` for channel ID allowlisting | -| WeChat (experimental) | None. Captured via host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | -| WhatsApp (experimental) | None. Pair via QR after rebuild | None | +| WeChat (experimental) | None. Captured through host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | +| WhatsApp (experimental) | None. Pair through QR after rebuild | None | Telegram uses a bot token from [BotFather](https://t.me/BotFather). Open Telegram, send `/newbot` to [@BotFather](https://t.me/BotFather), follow the prompts, and copy the token. @@ -56,23 +68,25 @@ Set `DISCORD_USER_ID` to restrict access to one user; otherwise, any member of t Slack uses Socket Mode and requires two tokens. Use `SLACK_BOT_TOKEN` for the bot user OAuth token (`xoxb-...`) and `SLACK_APP_TOKEN` for the app-level Socket Mode token (`xapp-...`). +NemoClaw validates both tokens before it saves Slack credentials or enables the channel. Set `SLACK_ALLOWED_USERS` to comma-separated Slack member IDs to authorize those users for DMs and for channel `@mention` events in channels where the Slack app is present. Set `SLACK_ALLOWED_CHANNELS` to comma-separated Slack channel IDs to restrict channel `@mention` handling to those channels. When both Slack allowlists are set, NemoClaw requires the mention to come from one of the allowed channels and one of the allowed members. Channel messages still require an explicit bot mention. +During sandbox startup, NemoClaw normalizes OpenShell credential placeholders into the environment shape expected by the Slack runtime, so post-rebuild Slack starts use the gateway-managed tokens instead of literal placeholder strings. -WeChat (experimental) delivers messages over Tencent's iLink gateway via the upstream `@tencent-weixin/openclaw-weixin` plugin baked into the sandbox base image and the built-in Hermes iLink WeChat adapter. +WeChat (experimental) delivers messages over Tencent's iLink gateway through the upstream `@tencent-weixin/openclaw-weixin` plugin baked into the sandbox base image and the built-in Hermes iLink WeChat adapter. The supported mode in this release is **personal WeChat** (`bot_type=3`). WeChat Official Account and WeCom/Enterprise WeChat are not wired up. Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemoclaw onboard`. You scan the QR with WeChat on your phone (Discover → Scan), confirm the login, and NemoClaw captures the token, `accountId`, `baseUrl`, and `userId` from the iLink response. NemoClaw registers the token as the `-wechat-bridge` OpenShell provider and substitutes the `openshell:resolve:env:WECHAT_BOT_TOKEN` placeholder for it inside the sandbox, so the token never lands in the image or on disk inside the running container. -The non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) is baked into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake. +NemoClaw bakes the non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake. WeChat is DM-only (`allowIdsMode: "dm"`). NemoClaw adds the operator who scanned the QR to `WECHAT_ALLOWED_IDS` automatically, and you can append more comma-separated WeChat user IDs through the same env var. -You can silence the host-side `[wechat]` diagnostic lines (poll status, IDC redirects, swallowed gateway errors) by exporting `NEMOCLAW_WECHAT_QUIET=1` once the flow is stable in your environment. +You can silence the host-side `[wechat]` diagnostic lines (poll status, IDC redirects, swallowed gateway errors) by exporting `NEMOCLAW_WECHAT_QUIET=1` after the flow is stable in your environment. Tencent's iLink gateway is a third-party service. Review your organization's terms-of-service, compliance, and data-residency constraints before enabling WeChat. @@ -80,14 +94,17 @@ Review your organization's terms-of-service, compliance, and data-residency cons WhatsApp (experimental) Web does not use a host-side token or OpenShell credential provider. NemoClaw advertises WhatsApp for both OpenClaw and Hermes sandboxes, and each agent completes pairing with its own in-sandbox command. Pairing happens inside the sandbox after the rebuild completes and creates mutable session credentials there. -Run `openshell term` and then use the agent-specific pairing command to render the QR code in the terminal: +Connect to the sandbox and then use the agent-specific pairing command to render the QR code in the terminal: -```console -$ openclaw channels login --channel whatsapp # OpenClaw sandboxes -$ hermes whatsapp # Hermes sandboxes +```bash +openclaw channels login --channel whatsapp # OpenClaw sandboxes +hermes whatsapp # Hermes sandboxes ``` -Session credentials are generated and stored inside durable agent state (`whatsapp` for OpenClaw, `platforms/whatsapp` for Hermes), so they survive rebuilds without re-pairing. +For OpenClaw sandboxes, NemoClaw validates the gateway URL before pairing and renders the WhatsApp QR code in a compact terminal form so it fits in smaller terminal windows. +If pairing exits with a gateway close such as `1008`, rerun the login command one time and then check `nemoclaw channels status --channel whatsapp` so you can diagnose the gateway/session path separately from QR rendering. + +The sandbox generates and stores session credentials inside durable agent state (`whatsapp` for OpenClaw, `platforms/whatsapp` for Hermes), so they survive rebuilds without re-pairing. This is the runtime tradeoff of enabling WhatsApp without a host bridge: a paired sandbox can use that WhatsApp account until you unpair it or clear the durable state. NemoClaw cannot detect cross-sandbox WhatsApp conflicts the way it does for token-based channels. Pair only one sandbox per WhatsApp account at a time. @@ -96,6 +113,7 @@ Pair only one sandbox per WhatsApp account at a time. When the wizard reaches **Messaging channels**, it lists Telegram, Discord, Slack, WeChat, and WhatsApp. Press a channel number to toggle it on or off, then press **Enter** when done. +If you select no channels, pressing **Enter** skips messaging setup. If a token-based channel token is not already in the environment or credential store, the wizard prompts for it and saves it. If you enable WeChat (experimental), the wizard does not prompt for a paste token. @@ -109,15 +127,15 @@ NemoClaw also selects the matching network policy preset during policy setup so For scripted setup, export the credentials and optional settings for the channels you want to enable before you run onboarding: -```console -$ export TELEGRAM_BOT_TOKEN= -$ export TELEGRAM_REQUIRE_MENTION=1 -$ export DISCORD_BOT_TOKEN= -$ export DISCORD_SERVER_ID= -$ export SLACK_BOT_TOKEN= -$ export SLACK_APP_TOKEN= -$ export SLACK_ALLOWED_USERS= -$ export SLACK_ALLOWED_CHANNELS= +```bash +export TELEGRAM_BOT_TOKEN= +export TELEGRAM_REQUIRE_MENTION=1 +export DISCORD_BOT_TOKEN= +export DISCORD_SERVER_ID= +export SLACK_BOT_TOKEN= +export SLACK_APP_TOKEN= +export SLACK_ALLOWED_USERS= +export SLACK_ALLOWED_CHANNELS= ``` This release does not support non-interactive WeChat configuration because the iLink QR handshake requires a human to scan the QR on a paired phone. @@ -125,8 +143,8 @@ Run `nemoclaw onboard` interactively when you want to enable WeChat. Then run onboarding: -```console -$ nemoclaw onboard +```bash +nemoclaw onboard ``` Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `-telegram-bridge` or `-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. @@ -136,49 +154,56 @@ Complete the rest of the wizard so the blueprint can create OpenShell providers Run channel commands from the host, not from inside the sandbox. Use `channels list` to see the supported channel names: -```console -$ nemoclaw my-assistant channels list +```bash +nemoclaw my-assistant channels list ``` Add the channel you want: -```console -$ nemoclaw my-assistant channels add telegram -$ nemoclaw my-assistant channels add discord -$ nemoclaw my-assistant channels add slack -$ nemoclaw my-assistant channels add wechat -$ nemoclaw my-assistant channels add whatsapp +```bash +nemoclaw my-assistant channels add telegram +nemoclaw my-assistant channels add discord +nemoclaw my-assistant channels add slack +nemoclaw my-assistant channels add wechat +nemoclaw my-assistant channels add whatsapp ``` `channels add` collects whatever each channel needs. It prompts for Telegram, Discord, and Slack tokens, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild. -It registers bridge providers with the OpenShell gateway when tokens were captured, records the channel in the sandbox registry, and asks whether to rebuild immediately. +It registers bridge providers with the OpenShell gateway when it captures tokens, records the channel in the sandbox registry, and asks whether to rebuild immediately. The command accepts mixed-case input such as `Telegram`, then stores and prints the canonical lowercase channel name. -If a matching built-in network policy preset exists, `channels add` applies it to the sandbox automatically before the rebuild so the bridge has egress to its upstream API. -If applying the preset fails, NemoClaw warns and tells you to re-apply manually with `nemoclaw policy-add ` after the rebuild. +`channels add` requires the matching built-in network policy preset YAML to be present. +A missing or malformed preset YAML (no `network_policies:` section) aborts the command before any token prompt, registry write, or rebuild prompt, so the sandbox never advertises a channel without a matching network policy. +With the preset file in place, `channels add` applies it to the sandbox before the rebuild so the bridge has egress to its upstream API. +When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean ` warning so the operator can clean up manually. +When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers. +It flags `gateway-providers` as residual because the in-flight upsert can leave the gateway with the new token. +Verify the gateway bridge before relying on the channel. +Restore the preset YAML and re-run `nemoclaw channels add `. Choose the rebuild so the running sandbox image picks up the new channel. +For Telegram, Discord, and Slack, `channels add` also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning. If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts. Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to test inbound agent replies, send a message from the Telegram client as an allowed user. For a repeatable live Telegram reply check, run `test/e2e/test-messaging-providers.sh` with `TELEGRAM_BOT_TOKEN_REAL`, `TELEGRAM_AUTHORIZED_CHAT_IDS` or `TELEGRAM_CHAT_ID`, and `NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E=1`. If you defer the rebuild, apply the change later: -```console -$ nemoclaw my-assistant rebuild +```bash +nemoclaw my-assistant rebuild ``` In non-interactive mode, set the required environment variables before running `channels add`. Missing credentials fail fast, and the command queues the change for a manual rebuild: -```console -$ NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ +```bash +NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ nemoclaw my-assistant channels add telegram -$ nemoclaw my-assistant rebuild +nemoclaw my-assistant rebuild ``` For Discord server access after onboarding, include the server settings when you add the channel and rebuild: -```console -$ DISCORD_BOT_TOKEN= \ +```bash +DISCORD_BOT_TOKEN= \ DISCORD_SERVER_ID= \ DISCORD_REQUIRE_MENTION=1 \ nemoclaw my-assistant channels add discord @@ -189,15 +214,15 @@ $ DISCORD_BOT_TOKEN= \ `channels add wechat` (experimental) follows the same shape as the other channels with two differences driven by the iLink QR handshake. First, the command does not prompt for a paste token. -Instead, it renders a QR code in your terminal, polls Tencent's iLink gateway, and captures both the bot token and the per-account metadata (`accountId`, `baseUrl`, `userId`) once you scan the QR with WeChat on your phone (Discover → Scan). +Instead, it renders a QR code in your terminal, polls Tencent's iLink gateway, and captures both the bot token and the per-account metadata (`accountId`, `baseUrl`, `userId`) after you scan the QR with WeChat on your phone (**Discover** > **Scan**). The login has an eight-minute deadline and refreshes the QR up to three times on expiry. Keep the terminal in the foreground until you see `✓ WeChat login confirmed`. Second, the command requires an interactive terminal. Non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`) fails fast with a clear error because the QR handshake needs a paired phone. -```console -$ nemoclaw my-assistant channels add wechat +```bash +nemoclaw my-assistant channels add wechat ``` If `WECHAT_BOT_TOKEN` is already cached for this sandbox (the operator onboarded with WeChat earlier), `channels add wechat` reuses the cached token and skips the QR scan to keep the upstream plugin's existing iLink session intact. @@ -213,9 +238,9 @@ Rebuild the sandbox after the update so the image reflects the current channel s To remove a channel and clear its stored credentials, run: -```console -$ nemoclaw my-assistant channels remove telegram -$ nemoclaw my-assistant channels remove wechat +```bash +nemoclaw my-assistant channels remove telegram +nemoclaw my-assistant channels remove wechat ``` `channels remove wechat` clears the bot token, deletes the `-wechat-bridge` OpenShell provider, and drops `wechat` from the sandbox's enabled-channel set. @@ -227,21 +252,27 @@ The cleanup tries `openshell sandbox exec` and falls back to SSH if that does no If neither transport can reach a running sandbox for a QR-paired channel, the command exits non-zero and asks you to start the sandbox and re-run. NemoClaw deliberately leaves the registry, policy preset, and `session.policyPresets` unchanged on that failure path, so a follow-up re-run completes the removal cleanly. -`channels remove whatsapp` clears the client-side Baileys session inside the sandbox; it cannot deregister the linked device with WhatsApp's servers because that requires an active Baileys connection to issue the logout RPC, which we no longer have once the session files are gone. +`channels remove whatsapp` clears the client-side Baileys session inside the sandbox. +It cannot deregister the linked device with WhatsApp's servers because that requires an active Baileys connection to issue the logout RPC, and the command no longer has that connection after it removes the session files. The phone account will continue to list the sandbox as a Linked Device until you remove it manually from your phone (Settings → Linked Devices → tap the entry → Log out) or until WhatsApp's 14-day inactivity timeout expires. -Removing the entry from the phone is recommended if you plan to re-pair the same phone with a different sandbox. +Remove the entry from the phone if you plan to re-pair the same phone with a different sandbox. Use `channels stop` when you want to pause a bridge without deleting credentials: -```console -$ nemoclaw my-assistant channels stop telegram -$ nemoclaw my-assistant channels start telegram +```bash +nemoclaw my-assistant channels stop telegram +nemoclaw my-assistant channels start telegram -$ nemoclaw my-assistant channels stop wechat -$ nemoclaw my-assistant channels start wechat +nemoclaw my-assistant channels stop wechat +nemoclaw my-assistant channels start wechat ``` + For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.openclaw/openclaw-weixin/accounts/` intact even though the bridge is no longer wired up in `openclaw.json`. + + +For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.hermes/` intact even though the bridge is no longer wired up in Hermes config. + A subsequent `channels start wechat` plus rebuild revives the bridge against the same iLink account without a fresh QR scan. The bot token is held by the OpenShell provider across the stop/start cycle. @@ -258,7 +289,12 @@ Re-run `channels add ` with the intended token to refresh the stored no ## Stop Messaging Delivery Use `channels stop` when you want to pause one bridge and keep the sandbox running. + Use `nemoclaw tunnel stop` or its deprecated alias `nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox. + + +Use `nemoclaw tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox. + Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway. ## Confirm Delivery @@ -269,17 +305,29 @@ Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `wh ## Tunnel Command + When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL. + + +When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. + Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL. + `nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. The older `nemoclaw start` still works as a deprecated alias. + + +`nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. + -```console -$ nemoclaw tunnel start +```bash +nemoclaw tunnel start ``` ## Related Topics + - Deploy NemoClaw to a Remote GPU Instance (use the `nemoclaw-user-deploy-remote` skill) for remote deployment with messaging. + - Architecture (use the `nemoclaw-user-reference` skill) for how providers, the gateway, and the sandbox fit together. - Commands (use the `nemoclaw-user-reference` skill) for `channels add`, `channels remove`, `channels start`, `channels stop`, `tunnel start`, `tunnel stop`, and `status`. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md b/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md index 9450277507..e5e026974b 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md @@ -1,41 +1,82 @@ - - # Runtime Controls and Sandbox Mutability +import { AgentOnly } from "../_components/AgentGuide"; + This page explains which parts of a running NemoClaw sandbox can change immediately and which changes require a rebuild or re-onboard. -## What you can change at runtime +## What You Can Change at Runtime -NemoClaw applies its security posture in three layers — what is baked into the sandbox image at onboard, what is hot-reloadable on the running sandbox, and what requires a rebuild or re-onboard. +NemoClaw applies its security posture in three layers: what onboarding bakes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard. The table below maps each commonly changed item to the layer that owns it and the command that changes it. + + | Item | When the change takes effect | How to change it | |---|---|---| -| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw rebuild` after picking a different provider via `nemoclaw inference set` | +| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw rebuild` after picking a different provider with `nemoclaw inference set` | | Inference model on the current provider | Rebuild required for OpenClaw; hot-reloadable for managed routers | `nemoclaw rebuild` (OpenClaw) or `nemoclaw inference set` (router-based) | | Sub-agent (Hermes / OpenClaw / …) | Re-onboard required (the sub-agent and its workspace are baked at onboard) | `nemoclaw onboard --recreate-sandbox` | -| Network policy preset (slack, discord, telegram, brave, …) | Runtime — applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | -| Network allow-list (custom hosts) | Runtime — picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | +| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | +| Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | | Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw channels add ` then accept the rebuild prompt | | Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `nemoclaw channels stop ` then rebuild | -| Dashboard forward port | Runtime — port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | -| Dashboard bind address (loopback vs all interfaces) | Runtime — applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | -| Web search backend (Brave, Tavily, etc.) | Runtime via `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation** — no runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | +| Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | +| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | +| Default OpenClaw workspace template seed (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`) | Locked at first sandbox boot. Re-onboard required to change the bake-time choice. | Set `NEMOCLAW_MINIMAL_BOOTSTRAP=1` before `nemoclaw onboard` to skip default template seeding for new/pristine workspaces. **Does not delete files already present.** Partial mitigation for #2598 (cuts ~3k tokens of project-context overhead off OpenClaw's per-turn bootstrap injection). | +| Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | | Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | | GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | -| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime — hot-reloaded by OpenClaw on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned | -| `openclaw.json` keys (general — model, agents.list, web.backend, channel config, etc.) | Mixed. Individual keys still follow the rebuild rules in the rows above, such as provider switch requiring rebuild even after editing the JSON. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | +| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime. OpenClaw hot-reloads on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned | +| `openclaw.json` keys (general: model, agents.list, web.backend, channel config, and so on) | Mixed. Individual keys still follow the rebuild rules in the rows above, such as provider switch requiring rebuild even after editing the JSON. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | If a row above conflicts with what you observe, the runtime source of truth inside the sandbox is `/opt/nemoclaw/openclaw.json`; the host registry caches metadata but the image and OpenClaw read from the in-sandbox file. -## See also + + + +| Item | When the change takes effect | How to change it | +|---|---|---| +| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `nemoclaw inference set` for route changes, or `nemoclaw rebuild` after changing build-time settings | +| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemoclaw inference set` | +| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemoclaw onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` | +| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | +| Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | +| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw channels add ` then accept the rebuild prompt | +| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`/sandbox/.hermes/.env` and Hermes config are baked at image build time) | `nemoclaw channels stop ` then rebuild | +| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemoclaw connect` or `openshell forward start` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | +| Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | +| GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | +| Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `nemoclaw inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | + +If a row above conflicts with what you observe, the runtime source of truth for +Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`; the host +registry caches metadata but the image and Hermes runtime read from the +in-sandbox files. + + + +## See Also The mutability table above is a consolidated index of information that lives in more detail on per-topic pages: -- [Manage Sandbox Lifecycle](../SKILL.md) — full rebuild / re-onboard / upgrade workflow. -- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) — the rebuild path for provider and model changes. -- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) — runtime policy editing and operator approval flow. -- Security Best Practices (use the `nemoclaw-user-configure-security` skill) — the per-attack-surface posture table that this page complements. -- OpenClaw Security Controls (use the `nemoclaw-user-configure-security` skill) — application-layer controls that operate independently of NemoClaw. -- CLI Commands Reference (use the `nemoclaw-user-reference` skill) — full flag surface for every `nemoclaw` command, including the env vars that affect runtime behavior. + + +- [Manage Sandbox Lifecycle](../SKILL.md) for the full rebuild, re-onboard, and upgrade workflow. +- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for the rebuild path for provider and model changes. +- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) for runtime policy editing and operator approval flow. +- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the per-attack-surface posture table that this page complements. +- OpenClaw Security Controls (use the `nemoclaw-user-configure-security` skill) for application-layer controls that operate independently of NemoClaw. +- CLI Commands Reference (use the `nemoclaw-user-reference` skill) for the full flag surface for every `nemoclaw` command, including the environment variables that affect runtime behavior. + + + + +- [Manage Sandbox Lifecycle](../SKILL.md) for the full rebuild, re-onboard, and upgrade workflow. +- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for the runtime route and rebuild paths for provider and model changes. +- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) for runtime policy editing and operator approval flow. +- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the per-attack-surface posture table that this page complements. +- CLI Commands Reference (use the `nemoclaw-user-reference` skill) for the full flag surface for every `nemoclaw` and `nemoclaw` command, including the environment variables that affect runtime behavior. + + diff --git a/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md b/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md index b8b0731df8..a6d1a13b62 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md @@ -1,7 +1,9 @@ - - # Workspace Files +import { AgentOnly } from "../_components/AgentGuide"; + + + OpenClaw stores its personality, user context, and behavioral configuration in a set of Markdown files inside the sandbox. These files live at `/sandbox/.openclaw/workspace/` and are collectively called **workspace files**. @@ -11,7 +13,7 @@ These files live at `/sandbox/.openclaw/workspace/` and are collectively called |---|---| | `SOUL.md` | Defines the agent's persona, tone, and communication style. | | `USER.md` | Stores information about the human the agent assists. | -| `IDENTITY.md` | Short identity card — name, language, emoji, creature type. | +| `IDENTITY.md` | Short identity card with name, language, emoji, and creature type. | | `AGENTS.md` | Behavioral rules, memory conventions, safety guidelines, and session workflow. | | `MEMORY.md` | Curated long-term memory distilled from daily notes. | | `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | @@ -35,7 +37,7 @@ All workspace files reside inside the sandbox filesystem: ## Multi-Agent Deployments A single NemoClaw sandbox can host more than one OpenClaw agent. -When OpenClaw is configured with multiple named agents (e.g., a shared `main` agent +When you configure OpenClaw with multiple named agents (for example, a shared `main` agent plus per-user agents for a Teams-integrated deployment), each agent gets its own workspace directory alongside the default `workspace/`: @@ -49,27 +51,23 @@ workspace directory alongside the default `workspace/`: Each per-agent workspace contains the same Markdown file structure as the default (`SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `MEMORY.md`, `memory/`). -Files are per-agent — changes in `workspace-main/AGENTS.md` are not visible to +Files are per-agent. Changes in `workspace-main/AGENTS.md` are not visible to `workspace-support/`. -Persistence and snapshots are handled automatically for per-agent workspaces: -the sandbox entrypoint provisions each `workspace-/` directly under the -writable `.openclaw/` tree so state survives sandbox restart, and -`nemoclaw snapshot create` discovers every `workspace-/` directory -and includes it in the snapshot bundle alongside the default `workspace/`. +NemoClaw handles persistence and snapshots automatically for per-agent workspaces: +the sandbox entrypoint provisions each `workspace-/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `nemoclaw snapshot create` discovers every `workspace-/` directory and includes it in the snapshot bundle alongside the default `workspace/`. **Note:** Files that operators typically want consistent across every agent workspace (`AGENTS.md`, shared skills, common templates) are not synced automatically. -Each workspace is independent; changes in one don't propagate. Tracking -shared-file tooling (shared mount, `workspaces list` command) in -[#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). +Each workspace is independent, and changes in one do not propagate. +NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). ## Persistence Behavior Workspace files live in the sandbox's persistent state volume, not in the container image. -This means they survive normal container restarts, but they are deleted when you destroy the sandbox. +They survive normal container restarts, but NemoClaw deletes them when you destroy the sandbox. ### Preserved During Restart, Rebuild, and Upgrade @@ -83,7 +81,7 @@ It does not continue with a partial backup. ### Deleted During Sandbox Destroy Running `nemoclaw destroy` deletes the sandbox and its persistent state volume. -Workspace files are removed from the sandbox unless you created a snapshot or backup first. +NemoClaw removes workspace files from the sandbox unless you created a snapshot or backup first. **Warning:** @@ -103,3 +101,26 @@ You can edit them in two ways: - Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill) - [Backup and Restore workspace files](backup-restore.md) - Commands reference (use the `nemoclaw-user-reference` skill) + + + + +Hermes stores durable agent state under `/sandbox/.hermes/` instead of the OpenClaw workspace directory. +The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environment settings live in `/sandbox/.hermes/.env`, and runtime state such as logs, memory, platform sessions, and the SQLite state database lives under the same `.hermes` tree. + +## Important Hermes State + +| Path | Purpose | +|---|---| +| `/sandbox/.hermes/config.yaml` | NemoClaw-generated Hermes runtime configuration. | +| `/sandbox/.hermes/.env` | NemoClaw-generated environment and messaging placeholders. | +| `/sandbox/.hermes/state.db` | Hermes SQLite state database. | +| `/sandbox/.hermes/platforms/` | Messaging platform state, including QR-paired sessions such as WhatsApp. | +| `/sandbox/.hermes/logs/` | Hermes runtime logs. | +| `/sandbox/SOUL.md` | Durable top-level Hermes persona file preserved by NemoClaw snapshots. | + +## Editing State + +Prefer NemoClaw host commands for generated configuration such as model, provider, messaging, and policy settings. +Direct edits to `/sandbox/.hermes/config.yaml` or `/sandbox/.hermes/.env` can be overwritten by rebuilds. +Use `nemoclaw connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. diff --git a/skills/nemoclaw-user-monitor-sandbox/SKILL.md b/skills/nemoclaw-user-monitor-sandbox/SKILL.md index 80192e7c14..1915fb8619 100644 --- a/skills/nemoclaw-user-monitor-sandbox/SKILL.md +++ b/skills/nemoclaw-user-monitor-sandbox/SKILL.md @@ -4,9 +4,6 @@ description: "Inspects sandbox health, traces agent behavior, and diagnoses prob license: "Apache-2.0" --- - - - # Monitor Sandbox Activity and Debug Issues ## Prerequisites @@ -14,25 +11,27 @@ license: "Apache-2.0" - A running NemoClaw sandbox. - The OpenShell CLI on your `PATH`. +import { AgentOnly } from "../_components/AgentGuide"; + Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems. ## Check Sandbox Health Run the status command to view the sandbox state, gateway health, and active inference configuration: -```console -$ nemoclaw status +```bash +nemoclaw status ``` For local Ollama and local vLLM routes, `nemoclaw status` also probes the host-side health endpoint directly. -This catches a stopped local backend before you retry `inference.local` from inside the sandbox. +This check catches a stopped local backend before you retry `inference.local` from inside the sandbox. -Key fields in the output include the following: +Key output fields include: -- Sandbox details, which show the configured model, provider, GPU mode, and applied policy presets. -- Gateway and process health, which show whether NemoClaw can still reach the OpenShell gateway and whether the in-sandbox agent process is running. -- Inference health for local Ollama and local vLLM, which shows `healthy` or `unreachable` together with the probed local URL. -- NIM status, which shows whether a NIM container is running and healthy when that path is in use. +- Sandbox details show the configured model, provider, GPU mode, and applied policy presets. +- Gateway and process health show whether NemoClaw can still reach the OpenShell gateway and whether the in-sandbox agent process is running. +- Inference health for local Ollama and local vLLM shows `healthy` or `unreachable` together with the probed local URL. +- NIM status shows whether a NIM container is running and healthy when that path is in use. Run `nemoclaw status` on the host to check sandbox state. Use `openshell sandbox list` for the underlying sandbox details. @@ -41,22 +40,51 @@ Use `openshell sandbox list` for the underlying sandbox details. Stream the most recent log output from the blueprint runner and sandbox: -```console -$ nemoclaw logs +```bash +nemoclaw logs ``` To follow the log output in real time: +```bash +nemoclaw logs --follow +``` + +The `logs` command shows lifecycle and gateway output. +It does not export the structured per-session agent state that OpenClaw stores under `.openclaw/agents/`. + +## Inspect Agent Session State + +OpenClaw stores structured session state inside the sandbox. +Use these files when you need an audit trail, a compliance review surface, or replay tooling that includes assistant messages and tool activity. + +| File | Purpose | +|---|---| +| `/sandbox/.openclaw/agents/main/sessions/.jsonl` | Per-session event log. Use this file for audit trails and compliance dashboards. Records can include assistant messages, `thinking` blocks, tool calls, tool results, token usage, and cost metadata. | +| `/sandbox/.openclaw/agents/main/sessions/.trajectory.jsonl` | Lower-level trajectory data for fine-grained replay. This file can be large, so avoid using it for routine audit summaries. | +| `/sandbox/.openclaw/agents/main/sessions/sessions.json` | Session index that maps known session keys to their persisted state. | + +To inspect the session directory from the host, run a sandbox command: + +```console +$ nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions +``` + +To copy a session log for offline review, use the OpenShell sandbox download command: + ```console -$ nemoclaw logs --follow +$ openshell sandbox download /sandbox/.openclaw/agents/main/sessions/.jsonl . ``` +Treat exported session logs as sensitive data. +They can contain prompts, tool inputs, tool outputs, file paths, and cost metadata from the agent run. + ## Monitor Network Activity in the TUI Open the OpenShell terminal UI for a live view of sandbox network activity and egress requests: -```console -$ openshell term +```bash +openshell term ``` For a remote sandbox, SSH to the instance and run `openshell term` there. @@ -73,10 +101,18 @@ Refer to Approve or Deny Agent Network Requests (use the `nemoclaw-user-manage-p Run a test inference request to verify that the provider is responding: -```console -$ nemoclaw my-assistant connect -$ openclaw agent --agent main -m "Test inference" --session-id debug + +```bash +nemoclaw my-assistant connect +openclaw agent --agent main -m "Test inference" --session-id debug +``` + + +```bash +nemoclaw my-hermes connect +hermes ``` + If the request fails, check the following: diff --git a/skills/nemoclaw-user-overview/SKILL.md b/skills/nemoclaw-user-overview/SKILL.md index 41250f65ec..89f0056373 100644 --- a/skills/nemoclaw-user-overview/SKILL.md +++ b/skills/nemoclaw-user-overview/SKILL.md @@ -1,17 +1,15 @@ --- name: "nemoclaw-user-overview" -description: "Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Trigger keywords - nemoclaw ecosystem, openclaw openshell, nemoclaw vs openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw overview, openclaw always-on assistants, nvidia openshell, nvidia nemotron, nemoclaw release notes, nemoclaw changelog." +description: "Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Trigger keywords - nemoclaw overview, openclaw always-on assistants, hermes agent, nvidia openshell, nvidia nemotron, nemoclaw ecosystem, nemohermes, nemoclaw vs openshell, run hermes openshell sandbox, openclaw openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw release notes, nemoclaw changelog." license: "Apache-2.0" --- - - - -# Ecosystem +# NemoClaw User Overview ## References +- **Load [references/overview.md](references/overview.md)** when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. +- **Load [references/ecosystem-hermes.md](references/ecosystem-hermes.md)** when users ask about Hermes, OpenShell, and NemoClaw together, or when to use NemoClaw versus OpenShell for Hermes. Explains how Hermes, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond integrating OpenShell yourself, and when to prefer NemoHermes versus OpenShell. - **Load [references/ecosystem.md](references/ecosystem.md)** when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. - **Load [references/how-it-works.md](references/how-it-works.md)** for sandbox lifecycle and architecture mechanics; not for product definition (Overview) or multi-project placement (Ecosystem). Describes how NemoClaw works internally: CLI, plugin, blueprint runner, OpenShell orchestration, inference routing, and protection layers. -- **Load [references/overview.md](references/overview.md)** when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Explains what NemoClaw covers: onboarding, lifecycle management, and OpenClaw operations within OpenShell containers, plus capabilities and why it exists. - **Load [references/release-notes.md](references/release-notes.md)** when users ask about recent changes, the release cadence, or where to track versioned assets on GitHub. Includes the NemoClaw release notes. diff --git a/skills/nemoclaw-user-overview/references/ecosystem-hermes.md b/skills/nemoclaw-user-overview/references/ecosystem-hermes.md new file mode 100644 index 0000000000..ae660f0ad6 --- /dev/null +++ b/skills/nemoclaw-user-overview/references/ecosystem-hermes.md @@ -0,0 +1,93 @@ +# Ecosystem + +NemoClaw provides onboarding, lifecycle management, and Hermes operations within OpenShell containers. +Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected. + +This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and how to choose between NemoHermes and OpenShell alone. + +## How the Stack Fits Together + +A NemoClaw for Hermes deployment combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw. +The following diagram shows how they fit together. + +```mermaid +flowchart TB + NC["🦞 NVIDIA NemoClaw
CLI, blueprint"] + OS["🐚 NVIDIA OpenShell
Gateway, policy, inference routing"] + HM["Hermes
Agent in sandbox"] + + NC -->|orchestrates| OS + OS -->|isolates and runs| HM + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class NC nv + class OS nv + class HM nvDark + + linkStyle 0 stroke:#76b900,stroke-width:2px + linkStyle 1 stroke:#76b900,stroke-width:2px +``` + +NemoClaw sits above OpenShell in the operator workflow. +It drives OpenShell APIs and CLI to create and configure the sandbox that runs Hermes. +Models and endpoints sit behind OpenShell's inference routing. +NemoClaw onboarding wires provider choice into that routing, including the Hermes Provider route when you onboard through `nemohermes`. + +The following table shows the scope of each component in the stack. + +| Project | Scope | +|---------|--------| +| [Hermes](https://hermes-agent.nousresearch.com/docs/) | The agent: runtime, tools, messaging adapters, and an OpenAI-compatible API inside the container. It does not define the sandbox or the host gateway. | +| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | +| NemoClaw | The NVIDIA reference stack on the host: `nemohermes` / `nemoclaw` CLI, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so Hermes runs inside OpenShell in a documented, repeatable way. | + +## NemoClaw Path versus OpenShell Path + +Both paths assume OpenShell can sandbox a workload. +The difference is who owns the integration work. + +| Path | What it means | +|------|---------------| +| **NemoClaw path** | You adopt the reference stack. NemoClaw's Hermes blueprint encodes a hardened image, default policies, and orchestration so `nemohermes onboard` can create a known-good Hermes-on-OpenShell setup with less custom glue. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | + +## What NemoClaw Adds Beyond Custom OpenShell + +You can run Hermes inside OpenShell without NemoClaw by building your own image, writing policy YAML, registering providers, and wiring inference routes yourself. +That path is valid when you need full control over the container layout. + +NemoClaw builds on OpenShell with additional security hardening, automation, and lifecycle tooling for Hermes. +The following table compares custom OpenShell integration with `nemohermes onboard`. + +| Capability | Custom OpenShell + Hermes | `nemohermes onboard` | +|---|---|---| +| Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. | +| Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. | +| Image hardening | Depends on your base image and install steps. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | +| Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. | +| Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates credentials from the host, configures the OpenShell route, and bakes model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. | +| Channel messaging | OpenShell delivers channel tokens through its provider system and L7 proxy; you configure Hermes platform adapters manually. | NemoClaw automates supported channel setup during onboarding and bakes Hermes env/config with placeholder tokens that OpenShell resolves at egress. | +| Blueprint versioning | No NemoClaw blueprint; your image tag is whatever you built locally. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemohermes onboard` on different machines produces the same sandbox. | +| State migration | Not included unless you build it. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. | +| Process count limits | You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint on top of OpenShell's seccomp and privilege dropping. | + +## When to Use Which + +Use the following table to decide when to use NemoHermes versus OpenShell alone. + +| Situation | Prefer | +|-----------|--------| +| You want Hermes with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw (`nemohermes`) | +| You need maximum flexibility for custom images, a layout that does not match the NemoClaw Hermes blueprint, or a workload outside this reference stack. | OpenShell with your own integration | +| You are standardizing on the NVIDIA reference for always-on Hermes agents with policy and inference routing. | NemoClaw (`nemohermes`) | +| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | + +## Related Topics + +- [Overview](overview.md) describes what NemoClaw is, including capabilities, benefits, and use cases. +- [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. diff --git a/skills/nemoclaw-user-overview/references/ecosystem.md b/skills/nemoclaw-user-overview/references/ecosystem.md index b1d97c4a22..a5a11e289c 100644 --- a/skills/nemoclaw-user-overview/references/ecosystem.md +++ b/skills/nemoclaw-user-overview/references/ecosystem.md @@ -1,14 +1,12 @@ - - # Ecosystem NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. -This page describes how the ecosystem is formed across projects, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. +This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. ## How the Stack Fits Together -There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope. +A NemoClaw for OpenClaw deployment combines three pieces with distinct scopes: OpenClaw, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid @@ -52,7 +50,7 @@ The difference is who owns the integration work. | Path | What it means | |------|---------------| -| **NemoClaw path** | You adopt the reference stack. NemoClaw's blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can stand up a known-good OpenClaw-on-OpenShell setup with less custom glue. | +| **NemoClaw path** | You adopt the reference stack. NemoClaw's blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can create a known-good OpenClaw-on-OpenShell setup with less custom glue. | | **OpenShell path** | You use OpenShell as the platform and supply your own container, install steps for OpenClaw, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond the OpenShell Community Sandbox @@ -70,7 +68,7 @@ The following table compares the two paths. | Credential handling | OpenShell's provider system replaces real credentials with placeholder tokens in the sandbox environment. The L7 proxy resolves placeholders to real values at egress. You create providers manually with `openshell provider create`. | NemoClaw creates OpenShell providers automatically during onboarding. It also filters sensitive host environment variables (provider API keys, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`) from the sandbox creation command to prevent accidental leakage through build args. | | Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | | Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. | -| Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host and are delivered through OpenShell's provider system. | +| Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host, and OpenShell's provider system delivers them. | | Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot/` URL pattern). You create providers and configure OpenClaw's channel settings manually. | NemoClaw automates channel setup during onboarding: it collects bot tokens, registers them as OpenShell providers, and bakes OpenClaw channel config with placeholder tokens that OpenShell's proxy resolves at egress. No separate bridge process runs on the host. | | Blueprint versioning | No blueprint. The community sandbox uses whatever image version is currently published. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemoclaw onboard` on different machines produces the same sandbox. | | State migration | Not included. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. | @@ -87,8 +85,8 @@ Use the following table to decide when to use NemoClaw versus OpenShell. | You are standardizing on the NVIDIA reference for always-on assistants with policy and inference routing. | NemoClaw | | You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | -## Related topics +## Related Topics -- [Overview](overview.md) contains what NemoClaw is, capabilities, benefits, and use cases. -- [How It Works](how-it-works.md) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers. +- [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. diff --git a/skills/nemoclaw-user-overview/references/how-it-works.md b/skills/nemoclaw-user-overview/references/how-it-works.md index b0f9f4a240..e21062559f 100644 --- a/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/skills/nemoclaw-user-overview/references/how-it-works.md @@ -1,11 +1,17 @@ - - # NemoClaw Architecture Overview -This page explains how NemoClaw runs OpenClaw inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. +import { AgentCli, AgentOnly } from "../_components/AgentGuide"; -NemoClaw does not replace OpenClaw or OpenShell. -It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, plugin configuration, and state helpers. +This page explains how NemoClaw runs supported agents inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. + +NemoClaw does not replace OpenShell or your chosen agent runtime. +It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, and state helpers. + +OpenClaw sandboxes also load the NemoClaw plugin for managed inference metadata and the `/nemoclaw` slash command. + + +Hermes sandboxes receive agent configuration under `/sandbox/.hermes` during onboarding instead of the OpenClaw plugin path. + You can use that setup directly or adapt it for your own OpenShell integration. ## High-Level Flow @@ -23,7 +29,7 @@ The diagram has the following components: | Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. | | NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. | | OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. | -| NemoClaw sandbox | Runs OpenClaw with the NemoClaw plugin, the selected blueprint contents, and supporting tools. | +| NemoClaw sandbox | Runs the onboarded agent with the selected blueprint contents and supporting tools. | | Inference | Receives model requests through the gateway, using NVIDIA endpoints, NIM, or compatible APIs. | | Integrations | Reach messaging services, MCP servers, GitHub, package indexes, or model hubs through gateway-managed egress. | | State and artifacts | Store configuration, credentials, logs, workspace files, policies, and transcripts outside the running agent process. | @@ -32,39 +38,48 @@ For repository layout, file paths, and deeper diagrams, see Architecture (use th ## Design Principles -NemoClaw architecture follows the following principles. +NemoClaw follows these architecture principles. -Thin plugin, versioned blueprint -: The sandbox plugin stays small and stable. Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. +Versioned blueprint +: Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. + The OpenClaw sandbox plugin stays small and stable inside the container. Respect CLI boundaries -: The `nemoclaw` CLI is the primary interface for sandbox management. +: The CLI is the primary interface for sandbox management. Supply chain safety : Blueprint artifacts are immutable, versioned, and digest-verified before execution. OpenShell-backed lifecycle -: NemoClaw orchestrates OpenShell resources under the hood, but `nemoclaw onboard` - is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes. +: NemoClaw orchestrates OpenShell resources under the hood, but onboard is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes. Reproducible setup : Running setup again recreates the sandbox from the same blueprint and policy definitions. ## CLI, Plugin, and Blueprint -NemoClaw is split into three integration pieces: +NemoClaw is split into integration pieces on the host and in the sandbox image: - The _host CLI_ runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations. + + - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + + + + +- NemoClaw writes Hermes runtime configuration into `/sandbox/.hermes` during onboarding, including `config.yaml`, environment files, and platform adapter settings for supported messaging channels. + + - The _blueprint_ is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell. -This separation keeps the sandbox plugin small while allowing host orchestration and blueprint contents to evolve on their own release cadence. +This separation keeps agent-specific sandbox assets focused while allowing host orchestration and blueprint contents to evolve on their own release cadence. ## Sandbox Creation -When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container. +When you run onboard, NemoClaw creates an OpenShell sandbox that runs your selected agent in an isolated container. The host CLI and blueprint runner orchestrate this process through the OpenShell CLI: 1. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest. @@ -80,6 +95,9 @@ OpenShell intercepts every inference call and routes it to the configured provid During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell route, and bakes the matching model reference into the sandbox image. The sandbox then talks to `inference.local`, while the host owns the actual provider credential and upstream endpoint. If you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. + +For Hermes, runtime model switches through inference set update `/sandbox/.hermes/config.yaml` without rebuilding the sandbox. + ## Protection Layers @@ -94,11 +112,24 @@ The sandbox starts with a default policy that controls network egress, filesyste When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. -For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill). For container-level hardening, refer to Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill). - ## Next Steps + + - Read [Ecosystem](ecosystem.md) for stack-level relationships and NemoClaw versus OpenShell-only paths. -- Follow the Quickstart (use the `nemoclaw-user-get-started` skill) to launch your first sandbox. +- Follow Quickstart with OpenClaw (use the `nemoclaw-user-get-started` skill) to launch your first sandbox. - Refer to the Architecture (use the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle. - Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for detailed provider configuration. +- For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill). +- For container-level hardening, refer to Sandbox Hardening. + + + + +- Read [Ecosystem](ecosystem.md) for stack-level relationships and NemoClaw versus OpenShell-only paths. +- Follow Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) to launch your first sandbox. +- Refer to the Architecture (use the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle. +- Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for detailed provider configuration. +- For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill). + + diff --git a/skills/nemoclaw-user-overview/references/overview.md b/skills/nemoclaw-user-overview/references/overview.md index ca25355fb5..a5dc5d525f 100644 --- a/skills/nemoclaw-user-overview/references/overview.md +++ b/skills/nemoclaw-user-overview/references/overview.md @@ -1,18 +1,19 @@ - - # Overview of NVIDIA NemoClaw -NVIDIA NemoClaw is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants more safely. -NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. -It incorporates policy-based privacy and security guardrails, giving you control over your agents’ behavior and data handling. -This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. +import { AgentCli, AgentOnly } from "../_components/AgentGuide"; + +NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside OpenShell containers. +NemoClaw provides onboarding, lifecycle management, and agent operations for supported runtimes in OpenShell sandboxes. +It incorporates policy-based privacy and security guardrails, giving you control over your agents' behavior and data handling. +These controls help self-evolving agents run more safely in clouds, on-premises environments, RTX PCs, and DGX Spark. NemoClaw pairs hosted models on inference providers or local endpoints with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. -The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell); NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run OpenClaw there. +The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). +NemoClaw adds the blueprint, CLI, onboarding, and related tooling as the reference way to run supported agents there. | Capability | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| Sandbox OpenClaw | Creates an OpenShell sandbox pre-configured for OpenClaw, with filesystem and network policies applied from the first boot. | +| Sandbox supported agents | Creates an OpenShell sandbox pre-configured for your selected agent, with filesystem and network policies applied from the first boot. | | Route inference | Configures OpenShell inference routing so agent traffic goes to the provider and model you chose during onboarding (NVIDIA Endpoints, OpenAI, Anthropic, Gemini, compatible endpoints, local Ollama, and others). The agent uses `inference.local` inside the sandbox; credentials stay on the host. | | Manage the lifecycle | Handles blueprint versioning, digest verification, and sandbox setup. | @@ -23,6 +24,7 @@ NemoClaw provides the following product capabilities. | Feature | Description | |---------|-------------| | Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. | +| Agent skills | Packages NemoClaw documentation as user skills so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. | | Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. | | State management | Safe migration of agent state across machines with credential stripping and integrity verification. | | Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | @@ -37,19 +39,19 @@ NemoClaw provides the following benefits to mitigate these risks. | Benefit | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------| -| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | -| Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). | -| Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | -| Single CLI | The `nemoclaw` command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | +| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. The sandbox grants no access by default. | +| Routed inference | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). | +| Declarative network policy | YAML defines egress rules. OpenShell blocks unknown hosts and surfaces them to the operator for approval. | +| Single CLI | The command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | | Blueprint lifecycle | Versioned blueprints handle sandbox creation, digest verification, and reproducible setup. | ## Use Cases -You can use NemoClaw for various use cases including the following. +You can use NemoClaw for use cases such as the following. | Use Case | Description | |---------------------------|----------------------------------------------------------------------------------------------| -| Always-on assistant | Run an OpenClaw assistant with controlled network access and operator-approved egress. | +| Always-on assistant | Run a sandboxed agent with controlled network access and operator-approved egress. | | Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | | Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | @@ -57,7 +59,21 @@ You can use NemoClaw for various use cases including the following. Navigate to the following topics to learn more about NemoClaw and how to install and use it. + + - [Architecture Overview](how-it-works.md) to understand how NemoClaw works. -- [Ecosystem](ecosystem.md) to understand how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- Quickstart (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first sandboxed agent. +- [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. - Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works. + + + + +- [Architecture Overview](how-it-works.md) to understand how NemoClaw works. +- [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. +- 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/skills/nemoclaw-user-overview/references/release-notes.md b/skills/nemoclaw-user-overview/references/release-notes.md index b5d7f664df..77747019bf 100644 --- a/skills/nemoclaw-user-overview/references/release-notes.md +++ b/skills/nemoclaw-user-overview/references/release-notes.md @@ -1,8 +1,81 @@ - - # Release Notes -NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track changes. +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.60 + +NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards: + +- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to Architecture (use the `nemoclaw-user-reference` skill). +- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from ` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). +- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). + +## v0.0.59 + +NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics: + +- OpenClaw sandboxes stay aligned with the live gateway and current runtime layout. Sandbox startup reconciles the agent model from the live gateway, refreshes the OpenClaw plugin registry after gateway startup, pins OpenClaw home, state, and workspace paths inside the sandbox, and handles OpenClaw 2026.5.27 approval compatibility. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Inference setup has newer model choices and longer first-start budgets for local runtimes. NVIDIA Endpoints includes the Nemotron 3 Ultra 550B option, Local Ollama uses `qwen3.5:9b` as the starter fallback, managed vLLM on DGX Spark uses a 128K context window for `nvidia/Qwen3.6-35B-A3B-NVFP4`, and Local NVIDIA NIM waits longer for first container startup while still failing fast when the container exits. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). +- Hermes sandboxes can route Anthropic Messages API traffic through managed inference, and runtime model switches keep the Hermes config synchronized with the OpenShell route. For more information, refer to Switch Inference Models at Runtime (use the `nemoclaw-user-configure-inference` skill). +- Credential and messaging boundaries are clearer during day-two operations. Rebuild and remote-provider update paths can reuse credentials already stored in the OpenShell gateway when the host environment is empty, `channels add` warns or aborts before multiple sandboxes compete for the same token-based messaging credential, and `status` reports cross-sandbox channel overlaps. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- Sandbox startup and host preflight failures provide more actionable recovery guidance. NemoClaw heals `~/.nemoclaw` directory and config-file permissions on read paths, detects missing or stale NVIDIA CDI specs before GPU containers fail, probes legacy gateway containers before host-alias operations, and preserves argument validation before runtime probing. For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). + +## v0.0.58 + +NemoClaw v0.0.58 improves GPU proof reporting, local-inference metadata, policy failure handling, Hermes messaging reliability, OpenClaw diagnostics, and release-prep documentation: + +- GPU and local-inference setup report more accurate state. WSL Docker Desktop on ARM64 can accept a reported NVIDIA GPU only after a bounded Docker CUDA proof succeeds, `nemoclaw status` shows whether sandbox CUDA usability is verified, unverified, or failed, managed vLLM uses runtime `max_model_len` metadata for the baked context window when available, and DeepSeek managed-vLLM startup receives the runtime keyword arguments it expects. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). +- Onboarding and installer failures stop earlier with clearer recovery guidance. The installer checks for `strings` from `binutils` before clone, build, or OpenShell download work; Docker-driver gateway startup fails fast when Docker is unreachable; WSL Docker Desktop diagnostics explain unsupported native Docker-in-WSL routes; Windows-host Ollama detection also checks the installed Windows process when the daemon is stopped; and custom proxy host and port settings are forwarded into the runtime container. For more information, refer to Prerequisites (use the `nemoclaw-user-get-started` skill). +- Policy and sandbox hardening paths avoid misleading success. `policy-add` refuses to merge a preset when the live policy read returns unparseable output, custom preset application reports when the gateway accepted a preset but the sandbox registry could not record it, and `NEMOCLAW_REQUIRE_CAP_DROP=1` lets operators make entrypoint capability dropping fail closed. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- OpenClaw runtime diagnostics can export conversation traces through the `diagnostics-otel` plugin. Set `NEMOCLAW_OPENCLAW_OTEL=1` before onboarding or rebuilding an OpenClaw sandbox to bake the plugin config and apply the local OTLP policy preset. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Hermes sandboxes are more reliable across messaging, inference, and startup repair paths. Slack channel rebuilds enable the Hermes Slack platform block, `inference.local` routes include the placeholder API key LiteLLM expects, Telegram pseudo-tool text is normalized only for the active chat platform, the messaging response patch preserves Hermes method binding, retry markers are cleared before explicit command dispatch, and Hermes state repair preserves writable history and background dispatcher behavior in locked runtime state. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). + +## v0.0.57 + +NemoClaw v0.0.57 improves multi-agent command workflows, local inference setup, messaging channel reliability, sandbox diagnostics, policy persistence, and installer pinning: + +- OpenClaw sandboxes can manage conversation sessions and secondary agents from the host CLI. Use `nemoclaw sessions` to list sessions, reset a session key through the OpenClaw gateway, or delete a non-main session, and use `nemoclaw agents add` or `nemoclaw agents delete` to invoke the in-sandbox OpenClaw agent commands. Build-time config also accepts `NEMOCLAW_EXTRA_AGENTS_JSON` so operators can bake validated secondary-agent entries into `agents.list` without replacing the primary `main` agent. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Local inference setup is more observable and more resilient. Managed vLLM on DGX Spark defaults to `nvidia/Qwen3.6-35B-A3B-NVFP4`, streams Hugging Face model-download progress, polls `/v1/models` for readiness, and uses a progress-aware Docker pull watchdog. Local Ollama routes request streaming usage metadata so OpenClaw token counters can update, and `connect` warns when the recorded inference route diverges from the live gateway route instead of reverting silently. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). +- Onboarding and re-onboarding preserve more operator intent. Linux Docker-driver onboarding can auto-apply a narrow UFW rule for the sandbox-to-gateway bridge when `NEMOCLAW_AUTO_FIX_FIREWALL=1`, verifies host-network local-inference reachability before reporting success, reuses healthy containerized gateways, binds gateway state by port, rolls back a freshly-created sandbox when setup is cancelled at the policy preset step, and carries finalized policy preset selections across later re-onboard runs. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Messaging channel setup fails earlier and leaves fewer partial changes. Slack setup validates both Socket Mode tokens before saving credentials, `channels add` checks the matching built-in policy preset before prompting or persisting channel state, failed preset application rolls back staged bridge changes when possible, WhatsApp pairing renders a compact QR code with clearer gateway diagnostics, and Slack runtime placeholders are normalized before OpenClaw starts. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- Sandbox status and repair output are more actionable. `nemoclaw status` reports Docker daemon, stopped-container, dashboard-port-conflict, and paused-container layers without running misleading inference probes, `doctor` skips stale Kubernetes-only gateway container checks on Docker-driver installs, and stale local registry entries are preserved so the suggested `rebuild --yes` recovery path still has the metadata it needs. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Installer and policy guidance tightened. Piped installs show the correct `NEMOCLAW_INSTALL_TAG` placement and fail clearly when a requested ref is unavailable, the `pypi` preset allows the `uv` package manager binary, and Jira validation now uses a body-visible Atlassian API probe so operators can distinguish blocked and approved curl traffic. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). + +## v0.0.56 + +NemoClaw v0.0.56 improves install safety, local-inference validation, messaging diagnostics, sandbox lifecycle reporting, and day-two command behavior: + +- Public installer and `nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill). +- `nemoclaw status`, `nemoclaw connect`, and `nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). +- Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- Command ergonomics are clearer for common day-two paths. `nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `nemoclaw status --json` supports per-sandbox automation, and `nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). +- Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). +- Uninstall, rebuild, and snapshot flows protect user state more consistently. `nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill). + +## v0.0.55 + +NemoClaw v0.0.55 improves local Ollama onboarding reliability, plugin secret-scanner resilience, and messaging-channel prompt clarity: + +- Local Ollama validation retries host-side curl process timeouts with a larger timeout before failing, and Docker runtime detection retries `docker info` before choosing the local inference route. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). +- The NemoClaw OpenClaw plugin keeps the memory secret scanner active when OpenClaw runs in embedded fallback mode without a usable path resolver. The scanner falls back to literal memory and workspace-relative paths instead of crashing before the first write-tool call. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). +- The onboarding messaging-channel picker now states that pressing Enter with no channels selected skips messaging setup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). + +## v0.0.54 + +NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHermes dashboard access, and sandbox repair paths: + +- Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). +- 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). +- 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). ## v0.0.53 @@ -217,20 +290,20 @@ NemoClaw v0.0.38 improves several day-two workflows: Starting with NemoClaw v0.0.34, the `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash` installer pipeline no longer auto-accepts the third-party software notice when stdin is piped and `/dev/tty` is unavailable (for example, deeply detached SSH sessions or some container shells). In environments without a TTY, accept upfront in the pipe: -```console -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash ``` Or pass the flag through to the installer: -```console -$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software +```bash +curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software ``` Or re-run from a terminal with a controlling TTY: -```console -$ bash <(curl -fsSL https://www.nvidia.com/nemoclaw.sh) +```bash +bash <(curl -fsSL https://www.nvidia.com/nemoclaw.sh) ``` The installer error message in v0.0.35+ surfaces all three invocations directly so users can copy-paste a recovery without leaving the terminal. diff --git a/skills/nemoclaw-user-reference/SKILL.md b/skills/nemoclaw-user-reference/SKILL.md index 25cb810e52..6d57867d78 100644 --- a/skills/nemoclaw-user-reference/SKILL.md +++ b/skills/nemoclaw-user-reference/SKILL.md @@ -9,7 +9,7 @@ license: "Apache-2.0" ## References - **Load [references/architecture.md](references/architecture.md)** when looking up architecture, agent integration, plugin structure, or blueprint design. Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. -- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. +- **Load [references/cli-selection-guide.md](references/cli-selection-guide.md)** when user asks to decide whether to use `$$nemoclaw` or `openshell`. Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. - **Load [references/commands.md](references/commands.md)** when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. - **Load [references/network-policies.md](references/network-policies.md)** when looking up a specific default endpoint, filesystem path, or the runtime approval sequence NemoClaw applies on blocked requests. Covers the baseline network policy, filesystem rules, and operator approval flow. - **Load [references/troubleshooting.md](references/troubleshooting.md)** when diagnosing a reported NemoClaw error, a failed onboard, or unexpected sandbox behavior. Lists fixes for common installation, onboarding, and runtime issues. diff --git a/skills/nemoclaw-user-reference/references/architecture.md b/skills/nemoclaw-user-reference/references/architecture.md index 07bbfc2ba9..62c053c186 100644 --- a/skills/nemoclaw-user-reference/references/architecture.md +++ b/skills/nemoclaw-user-reference/references/architecture.md @@ -68,8 +68,11 @@ graph LR The logical diagram above shows how components relate. This section shows what actually runs where on the host. NemoClaw's default Docker-driver topology does not place the sandbox in an embedded k3s cluster. -On Linux and Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. -The gateway normally runs as a host process; Linux hosts that need the gateway compatibility patch may run the same gateway binary inside a small container. +On Linux, NemoClaw configures and restarts the package-managed OpenShell gateway user service when it is installed, then creates the sandbox as a Docker container. +NemoClaw treats that service as authoritative only when `systemctl --user show openshell-gateway` reports a package/vendor unit path and an `openshell-gateway` `ExecStart`. +Per-user units, partial units, and user-manager or bus outages do not take over gateway ownership; NemoClaw falls back to the standalone gateway process used by earlier installs. +That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. +On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. diff --git a/skills/nemoclaw-user-reference/references/commands.md b/skills/nemoclaw-user-reference/references/commands.md index 4a632f4f6a..cf67f88a68 100644 --- a/skills/nemoclaw-user-reference/references/commands.md +++ b/skills/nemoclaw-user-reference/references/commands.md @@ -33,7 +33,7 @@ OpenClaw-specific sections below describe the `/nemoclaw` slash command, the Ope Use `nemohermes` for the Hermes variant. It selects Hermes by default during onboarding and for other commands. Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. -Hermes-specific sections below describe the OpenAI-compatible API endpoint, optional Hermes dashboard, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. +Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. ```bash nemohermes onboard # selects Hermes by default @@ -173,6 +173,9 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `bal NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` +Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. +Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. + `NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets. The default is `suggested`, which is *additive*. Onboarding applies tier defaults and preserves any presets you previously added with [`nemoclaw policy-add`](#nemoclaw-name-policy-add) across re-onboards. @@ -299,9 +302,10 @@ The poll count is clamped to a minimum of `1` so the probe always runs at least Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. -Onboarding skips common large directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. -It also skips credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`. -Other build outputs such as `dist/`, `target/`, or `build/` are still included. +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. 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. @@ -567,7 +571,7 @@ Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a new ```console $ nemoclaw my-assistant status ... - Agent: OpenClaw v2026.5.22 + Agent: OpenClaw v2026.5.27 ... ``` @@ -606,10 +610,35 @@ Warnings do not make the command fail. Failed checks exit non-zero so scripts can use `doctor` as a readiness gate. Use `--json` for machine-readable output. + + +For OpenClaw sandboxes, `doctor` also checks the mutable config permission contract. +If `openclaw doctor --fix` was run inside the sandbox, it can tighten `/sandbox/.openclaw` and `openclaw.json` to a single-user `700/600` layout, which stops the gateway from persisting config changes. +`doctor` reports this as a `Config permissions` warning; pass `--fix` to restore the group-writable `2770/660` contract without rebuilding. +Restarting the sandbox repairs the same drift automatically. + +```bash +nemoclaw my-assistant doctor [--json | --fix] +``` + +| Flag | Description | +|------|-------------| +| `--json` | Emit the report as JSON | +| `--fix` | Restore the mutable OpenClaw config permission contract if it was tightened. Mutually exclusive with `--json` | + + + + ```bash nemoclaw my-assistant doctor [--json] ``` +| Flag | Description | +|------|-------------| +| `--json` | Emit the report as JSON | + + + ### `nemoclaw logs` View sandbox logs. @@ -628,7 +657,9 @@ nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since -Print the authenticated OpenClaw dashboard URL for a running sandbox. +Print the browser dashboard URL for a running sandbox. +For OpenClaw sandboxes this includes the authenticated URL fragment. +For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL. Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session. ```bash @@ -647,14 +678,22 @@ URL=$(nemoclaw my-assistant dashboard-url --quiet) Treat the authenticated dashboard URL like a password. Do not log it, share it, or commit it to version control. +This warning applies when the command prints an OpenClaw tokenized URL. -`dashboard-url` is not applicable to Hermes sandboxes because Hermes exposes an OpenAI-compatible API endpoint instead of the OpenClaw dashboard URL. -Use `nemohermes my-assistant status` to find the forwarded API endpoint. -The Hermes API remains on port `8642` and uses `/v1` for OpenAI-compatible clients. -If you enabled `NEMOCLAW_HERMES_DASHBOARD=1`, use the optional Hermes dashboard port from the status output instead. +Print the browser dashboard URL for a running Hermes sandbox. +Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw `#token=` fragment. +The built-in dashboard is forwarded on port `18789` by default. + +```bash +nemohermes my-assistant dashboard-url +nemohermes my-assistant dashboard-url --quiet +``` + +The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for OpenAI-compatible clients. +Use `nemohermes my-assistant status` to see both the dashboard and API endpoints. @@ -1373,6 +1412,15 @@ nemoclaw tunnel stop `nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`. +### `nemoclaw tunnel status` + +Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +The output reports whether cloudflared is running, stopped, or stale, and includes the same recovery hint used by `nemoclaw status`. + +```console +nemoclaw tunnel status +``` + ### `nemoclaw start` **Warning:** @@ -1548,7 +1596,7 @@ Earlier releases only stopped `openshell forward` processes, so those orphans ac 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 PID files, SQLite data, audit logs, and VM-driver state. +On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-driver gateway SQLite data, audit logs, VM-driver state, and standalone-fallback gateway PID files. | Flag | Effect | |---|---| @@ -1690,15 +1738,14 @@ For OpenClaw, `NEMOCLAW_DASHBOARD_PORT` controls the OpenClaw dashboard forward. -For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the OpenAI-compatible API forward. -For Hermes sandboxes, `NEMOCLAW_HERMES_DASHBOARD=1` starts the native Hermes dashboard separately from the OpenAI-compatible API. -The Hermes API remains on port `8642`; the optional browser dashboard uses `NEMOCLAW_HERMES_DASHBOARD_PORT`. +For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the built-in dashboard forward, which defaults to `18789`. +The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for API clients. +Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-browser TUI tab. | Variable | Default | Service | |----------|---------|---------| -| `NEMOCLAW_HERMES_DASHBOARD` | 0 | Optional Hermes native web dashboard (`1`, `true`, `yes`, or `on` enables it) | -| `NEMOCLAW_HERMES_DASHBOARD_PORT` | 9119 | Optional Hermes native web dashboard forward port | -| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab when the dashboard is enabled | +| `NEMOCLAW_DASHBOARD_PORT` | 18789 | Hermes built-in dashboard forward port | +| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab | @@ -1725,7 +1772,7 @@ Set them before running `nemoclaw onboard`. | `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | | `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-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_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_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). | @@ -1830,9 +1877,9 @@ These flags toggle optional behaviors during onboarding; set them before running | `NEMOCLAW_SANDBOX_GPU` | `auto`, `1`, or `0` | Controls sandbox GPU passthrough during onboarding. `auto` enables GPU passthrough when an NVIDIA GPU is detected, `1` requires GPU passthrough, and `0` forces CPU-only sandbox creation. | | `NEMOCLAW_SANDBOX_GPU_DEVICE` | OpenShell GPU device selector | Selects the GPU device passed with `openshell sandbox create --gpu-device`. Requires explicit sandbox GPU enablement with `NEMOCLAW_SANDBOX_GPU=1` (or `--sandbox-gpu` for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in. | | `NEMOCLAW_DOCKER_GPU_PATCH` | `0` to disable, anything else to keep the default | Controls the Linux Docker-driver GPU sandbox compatibility patch. Set to `0` only as an escape hatch when the patch fails and you need onboarding to continue without patching the GPU sandbox container. | -| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver gateway. Defaults to the binary next to `openshell`, then common install paths. | -| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary passed to the Linux Docker-driver gateway supervisor. Defaults to the binary next to `openshell`, then common install paths. | -| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway pid file and SQLite state directory. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. | +| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. | +| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. | +| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. | | `NEMOCLAW_AUTO_FIX_FIREWALL` | `1` to enable | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs `sudo -n` only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command. | | `NEMOCLAW_WECHAT_QUIET` | `1` to enable | Silences the `[wechat]` diagnostic lines printed during the host-side WeChat QR login (poll status, IDC redirects, swallowed gateway errors), which are visible by default while the experimental WeChat path stabilizes; set `1` once the flow is reliable in your environment. | diff --git a/skills/nemoclaw-user-reference/references/network-policies.md b/skills/nemoclaw-user-reference/references/network-policies.md index de3517a690..99dabfc705 100644 --- a/skills/nemoclaw-user-reference/references/network-policies.md +++ b/skills/nemoclaw-user-reference/references/network-policies.md @@ -76,7 +76,8 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER`: NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` -If the value does not match a known tier, onboarding exits with an error listing the valid options. +Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. +If a non-blank value does not match a known tier, onboarding exits before preflight with an error listing the valid options. ### Inference diff --git a/skills/nemoclaw-user-reference/references/troubleshooting.md b/skills/nemoclaw-user-reference/references/troubleshooting.md index cdafbeb91a..6825c8152f 100644 --- a/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -837,7 +837,37 @@ Do not treat a failed `doctor --fix` run as proof that the Discord gateway path If `openclaw doctor` reports that it moved Telegram single-account values under `channels.telegram.accounts.default`, rerun onboarding and rebuild the sandbox rather than trying to patch `openclaw.json` in place. Current NemoClaw rebuilds bake Telegram in the account-based layout and set Telegram group chats to `groupPolicy: open`, which avoids the empty `groupAllowFrom` warning path for default group-chat access. -### Discord bot logs in, but the channel still does not work +### `openclaw doctor --fix` tightened config permissions and the gateway can no longer save config + +In a mutable NemoClaw sandbox, the gateway UID and the sandbox UID share the `sandbox` group, so `/sandbox/.openclaw` is setgid and group-writable (`2770`) and `openclaw.json` is group-writable (`660`). +OpenClaw's `openclaw doctor --fix` enforces its own single-user `700/600` layout, so running it inside the sandbox strips group write and breaks gateway-side config writes (for example, control-UI toggles that mutate `openclaw.json`). + +Repair the mutable contract without rebuilding: + +```bash +nemoclaw doctor --fix +``` + +`nemoclaw doctor` reports the drift as a `Config permissions` warning, and `--fix` restores `2770/660`. +Restarting the sandbox repairs the same drift automatically, and NemoClaw's own `rebuild` re-applies the contract after its post-upgrade `openclaw doctor --fix` step. + +When verifying gateway write access by hand, step down to the gateway UID with the image's installed mechanism so the `sandbox` group membership is initialized: + +```bash +setpriv --reuid=gateway --regid=gateway --init-groups -- sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json' +# or, where setpriv is unavailable: +gosu gateway sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json' +``` + +Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gateway's supplementary groups the same way, so a group-write probe can spuriously report `EACCES` even when the mutable contract is intact. + +A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: + +- **Mutable default (shields down):** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. +- **Shields up (locked from the host with `nemoclaw shields up`):** `openclaw.json` becomes `444 root:root` and the config dir becomes `755 root:root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). +- **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart. + +## Discord bot logs in, but the channel still does not work Separate the problem into two parts: From 8fad24ca9f90b899399559eeb8a583185f9e5d34 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 5 Jun 2026 17:27:38 -0700 Subject: [PATCH 2/4] docs: fill v0.0.60 release gaps --- .../SKILL.md | 6 ++++ .../references/inference-options.md | 6 ++++ .../references/switch-inference-providers.md | 14 ++++++++- .../references/tool-calling-reliability.md | 6 ++++ .../references/best-practices.md | 10 ++++--- .../references/credential-storage.md | 3 ++ .../skills/nemoclaw-user-get-started/SKILL.md | 4 +-- .../references/quickstart-hermes.md | 5 ++++ .../references/integration-policy-examples.md | 21 ++++++++++++++ .../nemoclaw-user-manage-sandboxes/SKILL.md | 2 ++ .../references/how-it-works.md | 2 ++ .../references/architecture.md | 7 +++-- .../references/commands.md | 29 ++++++++++++++++--- .../references/network-policies.md | 8 +++-- .../references/troubleshooting.md | 12 ++++++-- docs/about/how-it-works.mdx | 2 ++ docs/get-started/quickstart-hermes.mdx | 5 ++++ docs/get-started/quickstart.mdx | 4 +-- docs/inference/inference-options.mdx | 6 ++++ docs/inference/switch-inference-providers.mdx | 14 ++++++++- docs/inference/tool-calling-reliability.mdx | 6 ++++ docs/inference/use-local-inference.mdx | 6 ++++ docs/manage-sandboxes/lifecycle.mdx | 2 ++ .../integration-policy-examples.mdx | 21 ++++++++++++++ docs/reference/architecture.mdx | 7 +++-- docs/reference/commands-nemohermes.mdx | 22 +++++++++++--- docs/reference/commands.mdx | 29 ++++++++++++++++--- docs/reference/network-policies.mdx | 8 +++-- docs/reference/troubleshooting.mdx | 12 ++++++-- docs/security/best-practices.mdx | 10 ++++--- docs/security/credential-storage.mdx | 3 ++ fern/fern.config.json | 2 +- .../SKILL.md | 6 ++++ .../references/inference-options.md | 6 ++++ .../references/switch-inference-providers.md | 14 ++++++++- .../references/tool-calling-reliability.md | 6 ++++ .../references/best-practices.md | 10 ++++--- .../references/credential-storage.md | 3 ++ skills/nemoclaw-user-get-started/SKILL.md | 4 +-- .../references/quickstart-hermes.md | 5 ++++ .../references/integration-policy-examples.md | 21 ++++++++++++++ .../nemoclaw-user-manage-sandboxes/SKILL.md | 2 ++ .../evals/evals.json | 4 +-- .../references/how-it-works.md | 2 ++ .../references/architecture.md | 7 +++-- .../references/commands.md | 29 ++++++++++++++++--- .../references/network-policies.md | 8 +++-- .../references/troubleshooting.md | 12 ++++++-- 48 files changed, 372 insertions(+), 61 deletions(-) diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index a097a63abc..500792a4cf 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -175,6 +175,12 @@ NEMOCLAW_PROVIDER=ollama \ If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. +In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu. +If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit. +After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly. +When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default. +If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget. +This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU. `--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt. Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download. 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 c54a6d9032..8af6e446af 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -297,6 +297,7 @@ When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that v If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready. +Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image. If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting. The first run can take 10 to 30 minutes. @@ -378,6 +379,9 @@ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard Select **Local NVIDIA NIM [experimental]** from the provider list. NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. +On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index. +It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform. +If the registry does not expose a matching index, NemoClaw falls back to the tag pull. NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication. 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. @@ -385,6 +389,8 @@ The prompt masks the key during input and retries one time on a bad key before f 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 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. **Note:** diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md index 92089e996c..0a7a9b6d55 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -20,7 +20,7 @@ For OpenClaw, it updates `agents.defaults.model.primary` and the matching provid Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. -For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes. +For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes. Pass `--sandbox ` when you do not want to use the default registered sandbox. Under `nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. @@ -77,6 +77,16 @@ nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini +### API Family Sync + +Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses. +For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config. +For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes. +Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change. + +Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception. +When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode. + #### Switching from Responses API to Chat Completions If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. @@ -148,6 +158,8 @@ NemoClaw ignores invalid values and bakes the default into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. +During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid. +Non-interactive onboarding uses the environment value or the default `text` setting. ```bash export NEMOCLAW_CONTEXT_WINDOW=65536 diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md b/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md index d415ce4dda..5c13623091 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md @@ -38,6 +38,12 @@ The common failure mode is: This is different from a network or policy block. `nemoclaw status`, `nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation. +### Nemotron Managed Inference + +For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface. +That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed. +The agent still uses the structured tool-calling surface that the model handles correctly. + ## Recommended Fix For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**. diff --git a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md index 7893b472e4..d3cfa873a7 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -425,10 +425,10 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Aspect | Detail | |---|---| -| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. | -| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. | +| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. | +| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. | | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | -| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | +| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | @@ -436,6 +436,8 @@ The auto-pair watcher automatically approves device pairing requests from recogn Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. +Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials. +Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms. @@ -460,7 +462,7 @@ The scanner intercepts Write, Edit, and similar tool calls targeting memory and | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Three classifiers, all enforced through `isMemoryPath()`: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | +| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | 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 cdecf97052..26dc213e61 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -13,6 +13,9 @@ The sandbox-side OpenClaw gateway token is generated at container startup and is Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. +Those files should contain resolver placeholders, not live provider credentials. +For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. +Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. ## Where Credentials Live diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index c720ad2d2c..3056b491cd 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -70,7 +70,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. @@ -182,7 +182,7 @@ Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) befor After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. 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 4717cf5018..b475cdf1eb 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -59,6 +59,9 @@ Choose the inference provider that matches where you want Hermes model traffic t The provider options and credential environment variables are the same as the standard NemoClaw quickstart. For provider-specific prompts, refer to the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. +If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution. +Those choices add the matching Hermes policy presets to the sandbox. +API-key mode is inference-only and does not enable managed tool gateways. After provider and model selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. @@ -91,6 +94,8 @@ When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle co Hermes exposes its built-in browser dashboard on port `18789`. NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients. 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. Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text 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 18d77758ba..f28f5dff5f 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 @@ -48,9 +48,11 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr | OpenClaw model-pricing reference fetch | `openclaw-pricing` | | npm and Yarn packages | `npm` | | Microsoft 365, Outlook, and Graph API | `outlook` | +| Public reference APIs | `public-reference` | | Python Package Index | `pypi` | | Slack messaging | `slack` | | Telegram Bot API | `telegram` | +| Weather and geocoding APIs | `weather` | | WeChat (personal) iLink Bot API (experimental) | `wechat` | | WhatsApp Web messaging (experimental) | `whatsapp` | @@ -231,6 +233,25 @@ nemoclaw my-assistant policy-add brave --yes The Brave Search API key is still configured separately during onboarding or through the web search setup flow. +## Weather and Public Reference Lookups + +Use the `weather` preset when the agent needs read-only weather or geocoding lookups. +The Balanced and Open tiers include it by default. +The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs. + +```bash +nemoclaw my-assistant policy-add weather --dry-run +nemoclaw my-assistant policy-add weather --yes +``` + +Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. +The Open tier includes this preset by default. + +```bash +nemoclaw my-assistant policy-add public-reference --dry-run +nemoclaw my-assistant policy-add public-reference --yes +``` + ## Package and Model Tooling Use these presets when an agent workflow installs packages or downloads model assets: diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md index 9cb897f094..bc81066f59 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -113,6 +113,8 @@ When the default API port is already held by another sandbox, `nemoclaw onboard` If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. +Gateway and dashboard cleanup is scoped by sandbox name and port. +A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. ```bash nemoclaw onboard # first sandbox uses 18789 diff --git a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md index e21062559f..fd7a9108a5 100644 --- a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md @@ -65,6 +65,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. @@ -111,6 +112,7 @@ The sandbox starts with a default policy that controls network egress, filesyste | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. +NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. ## Next Steps diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md index 62c053c186..18ecd28a49 100644 --- a/.agents/skills/nemoclaw-user-reference/references/architecture.md +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -74,6 +74,7 @@ Per-user units, partial units, and user-manager or bus outages do not take over That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. +When `OPENSHELL_DRIVERS` includes `docker`, NemoClaw treats the gateway as host-owned and does not write the in-container `/tmp/nemoclaw-gateway-local` marker that legacy in-container gateway paths use. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -137,8 +138,10 @@ The concrete files differ by agent because each runtime has its own plugin syste | Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. -Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +This guidance stays out of the visible chat transcript. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. +The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors. The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint. @@ -200,7 +203,7 @@ runner still carries a pinned OpenShell Community OpenClaw image for legacy - Inference calls are routed through OpenShell to the configured provider. - Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. -- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately. +- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index cf67f88a68..d5db5d01a1 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -174,7 +174,8 @@ NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accep ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. +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*. @@ -184,6 +185,12 @@ 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, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. + + +Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. + + + | Value | Behaviour | |-------|-----------| | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | @@ -391,6 +398,7 @@ 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. ```bash nemoclaw list [--json] @@ -811,6 +819,8 @@ Custom presets bypass the built-in preset review process and can widen sandbox e List available policy presets and show which ones are applied to the sandbox. 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. ```bash nemoclaw my-assistant policy-list @@ -1014,6 +1024,9 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see Install OpenClaw Plugins. +For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory. +That mirror makes skills listed by `openclaw skills list` available at session startup. +If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions. @@ -1414,8 +1427,9 @@ nemoclaw tunnel stop ### `nemoclaw tunnel status` -Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +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. ```console nemoclaw tunnel status @@ -1442,6 +1456,7 @@ This command remains as a compatibility alias to `nemoclaw tunnel stop`. Show the sandbox list and the status of host auxiliary services (for example cloudflared). Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health. For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected. +Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```bash nemoclaw status @@ -1478,7 +1493,8 @@ For OpenClaw, the patch updates the OpenClaw config provider namespace and selec -For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) and does not rebuild or restart the gateway. +For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway. +Keeping the placeholder preserves dashboard and API authentication after provider switches. Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly. @@ -1769,10 +1785,13 @@ Set them before running `nemoclaw onboard`. | `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. | | `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. | | `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). | -| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. | +| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. | | `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. | | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_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). | @@ -1798,6 +1817,8 @@ Hermes-specific provider authentication: | `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. | | `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. | | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | +| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | +| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index 99dabfc705..937dd41abe 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -57,13 +57,14 @@ The baseline policy is always applied regardless of the selected tier. | Tier | Presets included | Description | |------|------------------|-------------| | Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported` | Full dev tooling and web search for agents that support web search. No messaging platform access. | -| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather` | Full dev tooling, read-only weather lookups, and web search for agents that support web search. No messaging platform access. | +| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather`, `public-reference`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging, productivity, weather, and public-reference APIs. | After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access. Tier-default presets are pre-selected; additional presets can be added from the full list. NemoClaw filters tier defaults by the active agent's supported integrations. For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration. +Hermes managed-tool gateway selections can add Hermes-specific presets, such as Nous-hosted web, image, audio, browser, or code tools, without applying unsupported OpenClaw-only presets. Claude Code direct egress is not included in any policy tier. If you install and run the Claude Code CLI inside the sandbox with its own credentials, apply the `claude-code` preset explicitly. Normal NemoClaw Anthropic inference still routes through the OpenShell gateway. @@ -77,7 +78,8 @@ NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-thir ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -If a non-blank value does not match a known tier, onboarding exits before preflight with an error listing the valid options. +In non-interactive onboarding, a non-blank value that does not match a known tier exits before preflight, gateway, or inference side effects and lists the valid options. +Interactive onboarding ignores an invalid environment value and shows the normal tier prompt. ### Inference diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 6825c8152f..3d85d5f1be 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -660,6 +660,8 @@ Region errors usually mean the pasted endpoint region, `AWS_REGION`, `AWS_DEFAUL For Ollama, vLLM, NIM, and compatible-endpoint inference validation, the default timeout is 180 seconds. The managed NIM startup health wait uses a separate 15-minute (900-second) default and still exits early if the container stops before it becomes healthy. +On Docker 29.x or hosts using the containerd image store, managed NIM onboarding resolves and pulls the host-platform image digest when NGC exposes a multi-architecture image index. +If you still see NGC repository-format or attestation errors, confirm Docker can run `docker manifest inspect` for the selected image and that you are logged in to `nvcr.io`. If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: ```bash @@ -668,6 +670,7 @@ nemoclaw onboard ``` For local Ollama and vLLM, onboarding retries the container reachability check and can fall back to the host-side health check when the local backend is healthy. +If Ollama times out during a cold model load, NemoClaw retries once with a 300-second probe budget before failing. If all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution. `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only covers the inference-server validation probe. @@ -863,8 +866,8 @@ Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gate A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: -- **Mutable default (shields down):** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. -- **Shields up (locked from the host with `nemoclaw shields up`):** `openclaw.json` becomes `444 root:root` and the config dir becomes `755 root:root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). +- **Mutable default:** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. +- **Host-locked state:** `openclaw.json` is read-only for in-sandbox writers and the config dir is owned by `root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). - **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart. ## Discord bot logs in, but the channel still does not work @@ -1281,6 +1284,9 @@ If onboarding reports `OpenShell supervisor did not reconnect to the GPU-enabled The reconnect wait debounces consecutive Error-phase polls before fast-failing, defaulting to fifteen consecutive polls of about 30 seconds in total. Increase the debounce window with `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_ERROR_DEBOUNCE` if your host needs more time to re-register the patched container, for example slow WSL2 + Docker Desktop setups. Set it to a higher integer such as `30` (about 60 seconds) and rerun onboarding; the value is clamped to a minimum of `1`. +If reconnect still fails after the GPU patch, NemoClaw attempts to restore the pre-patch CPU container before exiting. +When rollback succeeds, the output says the pre-patch sandbox was restored. +When rollback fails, the error says rollback failed and the pre-patch container was not restored, so inspect Docker state before retrying. ### `pip install` fails with a system-packages error @@ -1349,6 +1355,8 @@ If the process exists but the endpoint is unreachable, use the restart action wh Ollama configures context length based on your hardware. On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw. +During onboarding, NemoClaw raises loaded-model context lengths below `16384` to `16384` when `NEMOCLAW_CONTEXT_WINDOW` is unset. +Set the variable manually when you need a different value or when you run Ollama outside the managed onboarding path. Force a larger context length: ```bash diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 2c52d95b60..ff5303d993 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -74,6 +74,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. @@ -120,6 +121,7 @@ The sandbox starts with a default policy that controls network egress, filesyste | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. +NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. ## Next Steps diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index 1750682646..0fce090fdf 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -70,6 +70,9 @@ Choose the inference provider that matches where you want Hermes model traffic t The provider options and credential environment variables are the same as the standard NemoClaw quickstart. For provider-specific prompts, refer to the [Inference Options](../inference/inference-options) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. +If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution. +Those choices add the matching Hermes policy presets to the sandbox. +API-key mode is inference-only and does not enable managed tool gateways. After provider and model selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. @@ -102,6 +105,8 @@ When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle co Hermes exposes its built-in browser dashboard on port `18789`. NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients. 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. Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 8a023ad354..12a8d5a8bb 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -75,7 +75,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. @@ -187,7 +187,7 @@ Review [Messaging Channels](../manage-sandboxes/messaging-channels) before enabl After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 8285232195..182613a583 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -308,6 +308,7 @@ When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that v If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready. +Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image. If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting. The first run can take 10 to 30 minutes. @@ -389,6 +390,9 @@ NEMOCLAW_EXPERIMENTAL=1 $$nemoclaw onboard Select **Local NVIDIA NIM [experimental]** from the provider list. NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. +On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index. +It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform. +If the registry does not expose a matching index, NemoClaw falls back to the tag pull. NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication. 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. @@ -396,6 +400,8 @@ The prompt masks the key during input and retries one time on a bad key before f 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 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. NIM uses vLLM internally. diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index 7803512d1f..0313d8a8c8 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -31,7 +31,7 @@ For OpenClaw, it updates `agents.defaults.model.primary` and the matching provid Use `$$nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. -For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes. +For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes. Pass `--sandbox ` when you do not want to use the default registered sandbox. Under `$$nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. @@ -88,6 +88,16 @@ $$nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini +### API Family Sync + +Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses. +For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config. +For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes. +Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change. + +Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception. +When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode. + #### Switching from Responses API to Chat Completions If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. @@ -159,6 +169,8 @@ NemoClaw ignores invalid values and bakes the default into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. +During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid. +Non-interactive onboarding uses the environment value or the default `text` setting. ```bash export NEMOCLAW_CONTEXT_WINDOW=65536 diff --git a/docs/inference/tool-calling-reliability.mdx b/docs/inference/tool-calling-reliability.mdx index 653cb92022..9a5a4c2a5a 100644 --- a/docs/inference/tool-calling-reliability.mdx +++ b/docs/inference/tool-calling-reliability.mdx @@ -47,6 +47,12 @@ The common failure mode is: This is different from a network or policy block. `nemoclaw status`, `nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation. +### Nemotron Managed Inference + +For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface. +That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed. +The agent still uses the structured tool-calling surface that the model handles correctly. + ## Recommended Fix For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**. diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index 6dcb3ea6c2..f186516fc8 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -178,6 +178,12 @@ NEMOCLAW_PROVIDER=ollama \ If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. +In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu. +If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit. +After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly. +When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default. +If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget. +This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU. `--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt. Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download. diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 953a150544..7aa34c5d2c 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -118,6 +118,8 @@ When the default API port is already held by another sandbox, `$$nemoclaw onboar If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. +Gateway and dashboard cleanup is scoped by sandbox name and port. +A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. ```bash $$nemoclaw onboard # first sandbox uses 18789 diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 56b0ffe023..6ef410b6b9 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -59,9 +59,11 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr | OpenClaw model-pricing reference fetch | `openclaw-pricing` | | npm and Yarn packages | `npm` | | Microsoft 365, Outlook, and Graph API | `outlook` | +| Public reference APIs | `public-reference` | | Python Package Index | `pypi` | | Slack messaging | `slack` | | Telegram Bot API | `telegram` | +| Weather and geocoding APIs | `weather` | | WeChat (personal) iLink Bot API (experimental) | `wechat` | | WhatsApp Web messaging (experimental) | `whatsapp` | @@ -242,6 +244,25 @@ $$nemoclaw my-assistant policy-add brave --yes The Brave Search API key is still configured separately during onboarding or through the web search setup flow. +## Weather and Public Reference Lookups + +Use the `weather` preset when the agent needs read-only weather or geocoding lookups. +The Balanced and Open tiers include it by default. +The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs. + +```bash +$$nemoclaw my-assistant policy-add weather --dry-run +$$nemoclaw my-assistant policy-add weather --yes +``` + +Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. +The Open tier includes this preset by default. + +```bash +$$nemoclaw my-assistant policy-add public-reference --dry-run +$$nemoclaw my-assistant policy-add public-reference --yes +``` + ## Package and Model Tooling Use these presets when an agent workflow installs packages or downloads model assets: diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index d372ccbf5a..00350ca183 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -83,6 +83,7 @@ Per-user units, partial units, and user-manager or bus outages do not take over That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. +When `OPENSHELL_DRIVERS` includes `docker`, NemoClaw treats the gateway as host-owned and does not write the in-container `/tmp/nemoclaw-gateway-local` marker that legacy in-container gateway paths use. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -146,8 +147,10 @@ The concrete files differ by agent because each runtime has its own plugin syste | Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. -Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +This guidance stays out of the visible chat transcript. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. +The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors. The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint. @@ -209,7 +212,7 @@ runner still carries a pinned OpenShell Community OpenClaw image for legacy - Inference calls are routed through OpenShell to the configured provider. - Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. -- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately. +- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index bd5ca7a102..e465816db4 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -142,7 +142,8 @@ NEMOCLAW_POLICY_TIER=restricted nemohermes onboard --non-interactive --yes-i-acc ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. +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*. @@ -152,6 +153,8 @@ 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, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. +Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. + | Value | Behaviour | |-------|-----------| | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | @@ -343,6 +346,7 @@ 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. ```bash nemohermes list [--json] @@ -662,6 +666,8 @@ Custom presets bypass the built-in preset review process and can widen sandbox e List available policy presets and show which ones are applied to the sandbox. 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. ```bash nemohermes my-assistant policy-list @@ -1229,8 +1235,9 @@ nemohermes tunnel stop ### `nemohermes tunnel status` -Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +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 `nemohermes status`. +Selection honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```console nemohermes tunnel status @@ -1257,6 +1264,7 @@ This command remains as a compatibility alias to `nemohermes tunnel stop`. Show the sandbox list and the status of host auxiliary services (for example cloudflared). Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health. For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected. +Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```bash nemohermes status @@ -1286,7 +1294,8 @@ nemohermes inference get --json Switch the active inference provider or model for a NemoClaw-managed OpenClaw or Hermes 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. -For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) and does not rebuild or restart the gateway. +For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway. +Keeping the placeholder preserves dashboard and API authentication after provider switches. Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly. By default, the command syncs the default registered sandbox. @@ -1560,10 +1569,13 @@ Set them before running `nemohermes onboard`. | `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. | | `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. | | `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). | -| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. | +| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. | | `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. | | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see [Runtime Controls](../manage-sandboxes/runtime-controls). | | `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). | Hermes-specific provider authentication: @@ -1573,6 +1585,8 @@ Hermes-specific provider authentication: | `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. | | `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. | | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | +| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | +| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | #### Linux Ollama install mode details diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index e862f59e64..454819ec9c 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -183,7 +183,8 @@ NEMOCLAW_POLICY_TIER=restricted $$nemoclaw onboard --non-interactive --yes-i-acc ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. +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*. @@ -193,6 +194,12 @@ 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, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. + + +Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. + + + | Value | Behaviour | |-------|-----------| | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | @@ -400,6 +407,7 @@ 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. ```bash $$nemoclaw list [--json] @@ -836,6 +844,8 @@ Custom presets bypass the built-in preset review process and can widen sandbox e List available policy presets and show which ones are applied to the sandbox. 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. ```bash $$nemoclaw my-assistant policy-list @@ -1039,6 +1049,9 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). +For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory. +That mirror makes skills listed by `openclaw skills list` available at session startup. +If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions. @@ -1439,8 +1452,9 @@ $$nemoclaw tunnel stop ### `$$nemoclaw tunnel status` -Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +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. ```console $$nemoclaw tunnel status @@ -1467,6 +1481,7 @@ This command remains as a compatibility alias to `$$nemoclaw tunnel stop`. Show the sandbox list and the status of host auxiliary services (for example cloudflared). Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health. For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected. +Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```bash $$nemoclaw status @@ -1503,7 +1518,8 @@ For OpenClaw, the patch updates the OpenClaw config provider namespace and selec -For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) and does not rebuild or restart the gateway. +For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway. +Keeping the placeholder preserves dashboard and API authentication after provider switches. Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly. @@ -1794,10 +1810,13 @@ Set them before running `$$nemoclaw onboard`. | `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. | | `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. | | `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). | -| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. | +| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. | | `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. | | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see [Runtime Controls](../manage-sandboxes/runtime-controls). | | `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). | @@ -1823,6 +1842,8 @@ Hermes-specific provider authentication: | `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. | | `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. | | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | +| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | +| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | diff --git a/docs/reference/network-policies.mdx b/docs/reference/network-policies.mdx index f373cb7627..957c786c77 100644 --- a/docs/reference/network-policies.mdx +++ b/docs/reference/network-policies.mdx @@ -65,13 +65,14 @@ The baseline policy is always applied regardless of the selected tier. | Tier | Presets included | Description | |------|------------------|-------------| | Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported` | Full dev tooling and web search for agents that support web search. No messaging platform access. | -| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather` | Full dev tooling, read-only weather lookups, and web search for agents that support web search. No messaging platform access. | +| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather`, `public-reference`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging, productivity, weather, and public-reference APIs. | After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access. Tier-default presets are pre-selected; additional presets can be added from the full list. NemoClaw filters tier defaults by the active agent's supported integrations. For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration. +Hermes managed-tool gateway selections can add Hermes-specific presets, such as Nous-hosted web, image, audio, browser, or code tools, without applying unsupported OpenClaw-only presets. Claude Code direct egress is not included in any policy tier. If you install and run the Claude Code CLI inside the sandbox with its own credentials, apply the `claude-code` preset explicitly. Normal NemoClaw Anthropic inference still routes through the OpenShell gateway. @@ -85,7 +86,8 @@ NEMOCLAW_POLICY_TIER=open $$nemoclaw onboard --non-interactive --yes-i-accept-th ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -If a non-blank value does not match a known tier, onboarding exits before preflight with an error listing the valid options. +In non-interactive onboarding, a non-blank value that does not match a known tier exits before preflight, gateway, or inference side effects and lists the valid options. +Interactive onboarding ignores an invalid environment value and shows the normal tier prompt. ### Inference diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 39e7ed087c..326f13b5f4 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -675,6 +675,8 @@ Region errors usually mean the pasted endpoint region, `AWS_REGION`, `AWS_DEFAUL For Ollama, vLLM, NIM, and compatible-endpoint inference validation, the default timeout is 180 seconds. The managed NIM startup health wait uses a separate 15-minute (900-second) default and still exits early if the container stops before it becomes healthy. +On Docker 29.x or hosts using the containerd image store, managed NIM onboarding resolves and pulls the host-platform image digest when NGC exposes a multi-architecture image index. +If you still see NGC repository-format or attestation errors, confirm Docker can run `docker manifest inspect` for the selected image and that you are logged in to `nvcr.io`. If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: ```bash @@ -683,6 +685,7 @@ $$nemoclaw onboard ``` For local Ollama and vLLM, onboarding retries the container reachability check and can fall back to the host-side health check when the local backend is healthy. +If Ollama times out during a cold model load, NemoClaw retries once with a 300-second probe budget before failing. If all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution. `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only covers the inference-server validation probe. @@ -878,8 +881,8 @@ Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gate A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: -- **Mutable default (shields down):** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. -- **Shields up (locked from the host with `nemoclaw shields up`):** `openclaw.json` becomes `444 root:root` and the config dir becomes `755 root:root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). +- **Mutable default:** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. +- **Host-locked state:** `openclaw.json` is read-only for in-sandbox writers and the config dir is owned by `root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). - **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart. ### Discord bot logs in, but the channel still does not work @@ -1295,6 +1298,9 @@ If onboarding reports `OpenShell supervisor did not reconnect to the GPU-enabled The reconnect wait debounces consecutive Error-phase polls before fast-failing, defaulting to fifteen consecutive polls of about 30 seconds in total. Increase the debounce window with `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_ERROR_DEBOUNCE` if your host needs more time to re-register the patched container, for example slow WSL2 + Docker Desktop setups. Set it to a higher integer such as `30` (about 60 seconds) and rerun onboarding; the value is clamped to a minimum of `1`. +If reconnect still fails after the GPU patch, NemoClaw attempts to restore the pre-patch CPU container before exiting. +When rollback succeeds, the output says the pre-patch sandbox was restored. +When rollback fails, the error says rollback failed and the pre-patch container was not restored, so inspect Docker state before retrying. ### `pip install` fails with a system-packages error @@ -1362,6 +1368,8 @@ If the process exists but the endpoint is unreachable, use the restart action wh Ollama configures context length based on your hardware. On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw. +During onboarding, NemoClaw raises loaded-model context lengths below `16384` to `16384` when `NEMOCLAW_CONTEXT_WINDOW` is unset. +Set the variable manually when you need a different value or when you run Ollama outside the managed onboarding path. Force a larger context length: ```bash diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx index 63c530c821..dcf41cb7cd 100644 --- a/docs/security/best-practices.mdx +++ b/docs/security/best-practices.mdx @@ -450,10 +450,10 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Aspect | Detail | |---|---| -| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. | -| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. | +| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. | +| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. | | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | -| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | +| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | @@ -461,6 +461,8 @@ The auto-pair watcher automatically approves device pairing requests from recogn Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. +Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials. +Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms. @@ -485,7 +487,7 @@ The scanner intercepts Write, Edit, and similar tool calls targeting memory and | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Three classifiers, all enforced through `isMemoryPath()`: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | +| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | diff --git a/docs/security/credential-storage.mdx b/docs/security/credential-storage.mdx index 74043e38ec..7929751214 100644 --- a/docs/security/credential-storage.mdx +++ b/docs/security/credential-storage.mdx @@ -22,6 +22,9 @@ The sandbox-side OpenClaw gateway token is generated at container startup and is Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. +Those files should contain resolver placeholders, not live provider credentials. +For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. +Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. ## Where Credentials Live diff --git a/fern/fern.config.json b/fern/fern.config.json index 5495dca9a7..37536b72aa 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "nvidia", - "version": "5.44.3" + "version": "5.45.0" } diff --git a/skills/nemoclaw-user-configure-inference/SKILL.md b/skills/nemoclaw-user-configure-inference/SKILL.md index a097a63abc..500792a4cf 100644 --- a/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/skills/nemoclaw-user-configure-inference/SKILL.md @@ -175,6 +175,12 @@ NEMOCLAW_PROVIDER=ollama \ If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. +In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu. +If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit. +After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly. +When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default. +If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget. +This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU. `--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt. Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download. diff --git a/skills/nemoclaw-user-configure-inference/references/inference-options.md b/skills/nemoclaw-user-configure-inference/references/inference-options.md index c54a6d9032..8af6e446af 100644 --- a/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -297,6 +297,7 @@ When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that v If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready. +Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image. If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting. The first run can take 10 to 30 minutes. @@ -378,6 +379,9 @@ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard Select **Local NVIDIA NIM [experimental]** from the provider list. NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. +On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index. +It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform. +If the registry does not expose a matching index, NemoClaw falls back to the tag pull. NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication. 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. @@ -385,6 +389,8 @@ The prompt masks the key during input and retries one time on a bad key before f 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 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. **Note:** diff --git a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md index 92089e996c..0a7a9b6d55 100644 --- a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md +++ b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -20,7 +20,7 @@ For OpenClaw, it updates `agents.defaults.model.primary` and the matching provid Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. -For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes. +For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes. Pass `--sandbox ` when you do not want to use the default registered sandbox. Under `nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. @@ -77,6 +77,16 @@ nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini +### API Family Sync + +Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses. +For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config. +For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes. +Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change. + +Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception. +When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode. + #### Switching from Responses API to Chat Completions If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. @@ -148,6 +158,8 @@ NemoClaw ignores invalid values and bakes the default into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. +During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid. +Non-interactive onboarding uses the environment value or the default `text` setting. ```bash export NEMOCLAW_CONTEXT_WINDOW=65536 diff --git a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md index d415ce4dda..5c13623091 100644 --- a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md +++ b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md @@ -38,6 +38,12 @@ The common failure mode is: This is different from a network or policy block. `nemoclaw status`, `nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation. +### Nemotron Managed Inference + +For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface. +That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed. +The agent still uses the structured tool-calling surface that the model handles correctly. + ## Recommended Fix For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**. diff --git a/skills/nemoclaw-user-configure-security/references/best-practices.md b/skills/nemoclaw-user-configure-security/references/best-practices.md index 7893b472e4..d3cfa873a7 100644 --- a/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -425,10 +425,10 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Aspect | Detail | |---|---| -| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. | -| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. | +| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. | +| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. | | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | -| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | +| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | @@ -436,6 +436,8 @@ The auto-pair watcher automatically approves device pairing requests from recogn Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. +Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials. +Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms. @@ -460,7 +462,7 @@ The scanner intercepts Write, Edit, and similar tool calls targeting memory and | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Three classifiers, all enforced through `isMemoryPath()`: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | +| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | diff --git a/skills/nemoclaw-user-configure-security/references/credential-storage.md b/skills/nemoclaw-user-configure-security/references/credential-storage.md index cdecf97052..26dc213e61 100644 --- a/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -13,6 +13,9 @@ The sandbox-side OpenClaw gateway token is generated at container startup and is Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. +Those files should contain resolver placeholders, not live provider credentials. +For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. +Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. ## Where Credentials Live diff --git a/skills/nemoclaw-user-get-started/SKILL.md b/skills/nemoclaw-user-get-started/SKILL.md index c720ad2d2c..3056b491cd 100644 --- a/skills/nemoclaw-user-get-started/SKILL.md +++ b/skills/nemoclaw-user-get-started/SKILL.md @@ -70,7 +70,7 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. @@ -182,7 +182,7 @@ Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) befor After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. diff --git a/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index 4717cf5018..b475cdf1eb 100644 --- a/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -59,6 +59,9 @@ Choose the inference provider that matches where you want Hermes model traffic t The provider options and credential environment variables are the same as the standard NemoClaw quickstart. For provider-specific prompts, refer to the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. +If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution. +Those choices add the matching Hermes policy presets to the sandbox. +API-key mode is inference-only and does not enable managed tool gateways. After provider and model selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. @@ -91,6 +94,8 @@ When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle co Hermes exposes its built-in browser dashboard on port `18789`. NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients. 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. Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. ```text diff --git a/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md index 18d77758ba..f28f5dff5f 100644 --- a/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md +++ b/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -48,9 +48,11 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr | OpenClaw model-pricing reference fetch | `openclaw-pricing` | | npm and Yarn packages | `npm` | | Microsoft 365, Outlook, and Graph API | `outlook` | +| Public reference APIs | `public-reference` | | Python Package Index | `pypi` | | Slack messaging | `slack` | | Telegram Bot API | `telegram` | +| Weather and geocoding APIs | `weather` | | WeChat (personal) iLink Bot API (experimental) | `wechat` | | WhatsApp Web messaging (experimental) | `whatsapp` | @@ -231,6 +233,25 @@ nemoclaw my-assistant policy-add brave --yes The Brave Search API key is still configured separately during onboarding or through the web search setup flow. +## Weather and Public Reference Lookups + +Use the `weather` preset when the agent needs read-only weather or geocoding lookups. +The Balanced and Open tiers include it by default. +The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs. + +```bash +nemoclaw my-assistant policy-add weather --dry-run +nemoclaw my-assistant policy-add weather --yes +``` + +Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. +The Open tier includes this preset by default. + +```bash +nemoclaw my-assistant policy-add public-reference --dry-run +nemoclaw my-assistant policy-add public-reference --yes +``` + ## Package and Model Tooling Use these presets when an agent workflow installs packages or downloads model assets: diff --git a/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/skills/nemoclaw-user-manage-sandboxes/SKILL.md index 9cb897f094..bc81066f59 100644 --- a/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -113,6 +113,8 @@ When the default API port is already held by another sandbox, `nemoclaw onboard` If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. +Gateway and dashboard cleanup is scoped by sandbox name and port. +A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. ```bash nemoclaw onboard # first sandbox uses 18789 diff --git a/skills/nemoclaw-user-manage-sandboxes/evals/evals.json b/skills/nemoclaw-user-manage-sandboxes/evals/evals.json index ff6af55509..9553812c3f 100644 --- a/skills/nemoclaw-user-manage-sandboxes/evals/evals.json +++ b/skills/nemoclaw-user-manage-sandboxes/evals/evals.json @@ -31,9 +31,9 @@ }, { "id": "docs-manage-sandboxes-runtime-controls-003", - "question": "I'm responding to an incident or risky agent behavior. Help me use `shields up`, `shields down`, and `shields status` correctly so I can tighten or inspect controls without confusion.", + "question": "I'm responding to an incident or risky agent behavior. Help me inspect runtime controls and choose the safest recovery path without confusion.", "expected_skill": "nemoclaw-user-manage-sandboxes", - "ground_truth": "A NemoClaw-specific answer that helps the user use `shields up`, `shields down`, and `shields status` correctly and gives enough concrete guidance, decision criteria, verification steps, or risk framing to tighten or inspect controls without confusion." + "ground_truth": "A NemoClaw-specific answer that helps the user inspect runtime controls and choose the safest recovery path and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid confusion." }, { "id": "docs-manage-sandboxes-backup-restore-001", diff --git a/skills/nemoclaw-user-overview/references/how-it-works.md b/skills/nemoclaw-user-overview/references/how-it-works.md index e21062559f..fd7a9108a5 100644 --- a/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/skills/nemoclaw-user-overview/references/how-it-works.md @@ -65,6 +65,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. @@ -111,6 +112,7 @@ The sandbox starts with a default policy that controls network egress, filesyste | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. +NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. ## Next Steps diff --git a/skills/nemoclaw-user-reference/references/architecture.md b/skills/nemoclaw-user-reference/references/architecture.md index 62c053c186..18ecd28a49 100644 --- a/skills/nemoclaw-user-reference/references/architecture.md +++ b/skills/nemoclaw-user-reference/references/architecture.md @@ -74,6 +74,7 @@ Per-user units, partial units, and user-manager or bus outages do not take over That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. +When `OPENSHELL_DRIVERS` includes `docker`, NemoClaw treats the gateway as host-owned and does not write the in-container `/tmp/nemoclaw-gateway-local` marker that legacy in-container gateway paths use. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -137,8 +138,10 @@ The concrete files differ by agent because each runtime has its own plugin syste | Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. -Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +This guidance stays out of the visible chat transcript. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. +The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors. The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint. @@ -200,7 +203,7 @@ runner still carries a pinned OpenShell Community OpenClaw image for legacy - Inference calls are routed through OpenShell to the configured provider. - Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. -- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately. +- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. diff --git a/skills/nemoclaw-user-reference/references/commands.md b/skills/nemoclaw-user-reference/references/commands.md index cf67f88a68..d5db5d01a1 100644 --- a/skills/nemoclaw-user-reference/references/commands.md +++ b/skills/nemoclaw-user-reference/references/commands.md @@ -174,7 +174,8 @@ NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accep ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -Any non-blank value must be one of `restricted`, `balanced`, or `open`; otherwise onboarding exits before preflight with an error listing the valid options. +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*. @@ -184,6 +185,12 @@ 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, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. + + +Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. + + + | Value | Behaviour | |-------|-----------| | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | @@ -391,6 +398,7 @@ 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. ```bash nemoclaw list [--json] @@ -811,6 +819,8 @@ Custom presets bypass the built-in preset review process and can widen sandbox e List available policy presets and show which ones are applied to the sandbox. 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. ```bash nemoclaw my-assistant policy-list @@ -1014,6 +1024,9 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see Install OpenClaw Plugins. +For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory. +That mirror makes skills listed by `openclaw skills list` available at session startup. +If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions. @@ -1414,8 +1427,9 @@ nemoclaw tunnel stop ### `nemoclaw tunnel status` -Show the current cloudflared public-URL tunnel status for the default sandbox dashboard. +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. ```console nemoclaw tunnel status @@ -1442,6 +1456,7 @@ This command remains as a compatibility alias to `nemoclaw tunnel stop`. Show the sandbox list and the status of host auxiliary services (for example cloudflared). Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health. For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected. +Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```bash nemoclaw status @@ -1478,7 +1493,8 @@ For OpenClaw, the patch updates the OpenClaw config provider namespace and selec -For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) and does not rebuild or restart the gateway. +For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway. +Keeping the placeholder preserves dashboard and API authentication after provider switches. Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly. @@ -1769,10 +1785,13 @@ Set them before running `nemoclaw onboard`. | `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. | | `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. | | `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). | -| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. | +| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | +| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. | | `NEMOCLAW_INSTALL_REF` | git ref | For internal installer commands: the git ref to install from. Overridden by the `--install-ref` flag. | | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_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). | @@ -1798,6 +1817,8 @@ Hermes-specific provider authentication: | `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. | | `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. | | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | +| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | +| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | diff --git a/skills/nemoclaw-user-reference/references/network-policies.md b/skills/nemoclaw-user-reference/references/network-policies.md index 99dabfc705..937dd41abe 100644 --- a/skills/nemoclaw-user-reference/references/network-policies.md +++ b/skills/nemoclaw-user-reference/references/network-policies.md @@ -57,13 +57,14 @@ The baseline policy is always applied regardless of the selected tier. | Tier | Presets included | Description | |------|------------------|-------------| | Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported` | Full dev tooling and web search for agents that support web search. No messaging platform access. | -| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather` | Full dev tooling, read-only weather lookups, and web search for agents that support web search. No messaging platform access. | +| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather`, `public-reference`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging, productivity, weather, and public-reference APIs. | After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access. Tier-default presets are pre-selected; additional presets can be added from the full list. NemoClaw filters tier defaults by the active agent's supported integrations. For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration. +Hermes managed-tool gateway selections can add Hermes-specific presets, such as Nous-hosted web, image, audio, browser, or code tools, without applying unsupported OpenClaw-only presets. Claude Code direct egress is not included in any policy tier. If you install and run the Claude Code CLI inside the sandbox with its own credentials, apply the `claude-code` preset explicitly. Normal NemoClaw Anthropic inference still routes through the OpenShell gateway. @@ -77,7 +78,8 @@ NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-thir ``` Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -If a non-blank value does not match a known tier, onboarding exits before preflight with an error listing the valid options. +In non-interactive onboarding, a non-blank value that does not match a known tier exits before preflight, gateway, or inference side effects and lists the valid options. +Interactive onboarding ignores an invalid environment value and shows the normal tier prompt. ### Inference diff --git a/skills/nemoclaw-user-reference/references/troubleshooting.md b/skills/nemoclaw-user-reference/references/troubleshooting.md index 6825c8152f..3d85d5f1be 100644 --- a/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -660,6 +660,8 @@ Region errors usually mean the pasted endpoint region, `AWS_REGION`, `AWS_DEFAUL For Ollama, vLLM, NIM, and compatible-endpoint inference validation, the default timeout is 180 seconds. The managed NIM startup health wait uses a separate 15-minute (900-second) default and still exits early if the container stops before it becomes healthy. +On Docker 29.x or hosts using the containerd image store, managed NIM onboarding resolves and pulls the host-platform image digest when NGC exposes a multi-architecture image index. +If you still see NGC repository-format or attestation errors, confirm Docker can run `docker manifest inspect` for the selected image and that you are logged in to `nvcr.io`. If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: ```bash @@ -668,6 +670,7 @@ nemoclaw onboard ``` For local Ollama and vLLM, onboarding retries the container reachability check and can fall back to the host-side health check when the local backend is healthy. +If Ollama times out during a cold model load, NemoClaw retries once with a 300-second probe budget before failing. If all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution. `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only covers the inference-server validation probe. @@ -863,8 +866,8 @@ Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gate A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: -- **Mutable default (shields down):** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. -- **Shields up (locked from the host with `nemoclaw shields up`):** `openclaw.json` becomes `444 root:root` and the config dir becomes `755 root:root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). +- **Mutable default:** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. +- **Host-locked state:** `openclaw.json` is read-only for in-sandbox writers and the config dir is owned by `root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). - **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart. ## Discord bot logs in, but the channel still does not work @@ -1281,6 +1284,9 @@ If onboarding reports `OpenShell supervisor did not reconnect to the GPU-enabled The reconnect wait debounces consecutive Error-phase polls before fast-failing, defaulting to fifteen consecutive polls of about 30 seconds in total. Increase the debounce window with `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_ERROR_DEBOUNCE` if your host needs more time to re-register the patched container, for example slow WSL2 + Docker Desktop setups. Set it to a higher integer such as `30` (about 60 seconds) and rerun onboarding; the value is clamped to a minimum of `1`. +If reconnect still fails after the GPU patch, NemoClaw attempts to restore the pre-patch CPU container before exiting. +When rollback succeeds, the output says the pre-patch sandbox was restored. +When rollback fails, the error says rollback failed and the pre-patch container was not restored, so inspect Docker state before retrying. ### `pip install` fails with a system-packages error @@ -1349,6 +1355,8 @@ If the process exists but the endpoint is unreachable, use the restart action wh Ollama configures context length based on your hardware. On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw. +During onboarding, NemoClaw raises loaded-model context lengths below `16384` to `16384` when `NEMOCLAW_CONTEXT_WINDOW` is unset. +Set the variable manually when you need a different value or when you run Ollama outside the managed onboarding path. Force a larger context length: ```bash From 63bf71fb08bfbfad442f5f402257db90339d45df Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 5 Jun 2026 17:31:45 -0700 Subject: [PATCH 3/4] docs: exclude root skills refresh --- skills/nemoclaw-user-agent-skills/SKILL.md | 83 +---- .../references/agent-skills.md | 83 +++++ .../SKILL.md | 210 ++++++----- .../references/inference-options.md | 331 +----------------- .../references/set-up-sub-agent.md | 32 +- .../references/switch-inference-providers.md | 195 ++++------- .../references/tool-calling-reliability.md | 64 ++-- .../references/use-local-inference-details.md | 151 ++++++++ .../nemoclaw-user-configure-security/SKILL.md | 7 +- .../references/best-practices.md | 136 ++----- .../references/credential-storage.md | 43 +-- .../references/openclaw-controls.md | 10 +- skills/nemoclaw-user-deploy-remote/SKILL.md | 101 +++--- .../references/brev-web-ui.md | 12 +- .../references/install-openclaw-plugins.md | 57 +-- .../references/sandbox-hardening.md | 61 ++-- skills/nemoclaw-user-get-started/SKILL.md | 120 ++----- .../references/prerequisites.md | 29 +- .../references/quickstart-details.md | 165 +++++++++ .../references/quickstart-hermes.md | 124 +++---- .../references/windows-preparation.md | 48 +-- skills/nemoclaw-user-manage-policy/SKILL.md | 123 +++---- .../references/approve-network-requests.md | 14 +- .../customize-network-policy-details.md | 13 + .../references/integration-policy-examples.md | 241 ++++++------- .../nemoclaw-user-manage-sandboxes/SKILL.md | 195 +++++------ .../evals/evals.json | 4 +- .../references/backup-restore.md | 206 ++++------- .../references/install-plugins-hermes.md | 117 ------- .../references/lifecycle-details.md | 26 ++ .../references/messaging-channels.md | 166 ++++----- .../references/runtime-controls.md | 81 ++--- .../references/workspace-files.md | 51 +-- skills/nemoclaw-user-monitor-sandbox/SKILL.md | 74 +--- skills/nemoclaw-user-overview/SKILL.md | 10 +- .../references/ecosystem-hermes.md | 93 ----- .../references/ecosystem.md | 16 +- .../references/how-it-works.md | 69 +--- .../references/overview.md | 48 +-- .../references/release-notes.md | 91 +---- skills/nemoclaw-user-reference/SKILL.md | 2 +- .../references/architecture.md | 14 +- .../references/commands.md | 114 ++---- .../references/network-policies.md | 9 +- .../references/troubleshooting.md | 40 +-- 45 files changed, 1488 insertions(+), 2391 deletions(-) create mode 100644 skills/nemoclaw-user-agent-skills/references/agent-skills.md create mode 100644 skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md create mode 100644 skills/nemoclaw-user-get-started/references/quickstart-details.md create mode 100644 skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md delete mode 100644 skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md create mode 100644 skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md delete mode 100644 skills/nemoclaw-user-overview/references/ecosystem-hermes.md diff --git a/skills/nemoclaw-user-agent-skills/SKILL.md b/skills/nemoclaw-user-agent-skills/SKILL.md index fca8d94d8c..fd12b0566d 100644 --- a/skills/nemoclaw-user-agent-skills/SKILL.md +++ b/skills/nemoclaw-user-agent-skills/SKILL.md @@ -3,87 +3,8 @@ name: "nemoclaw-user-agent-skills" description: "Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. Use when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Trigger keywords - nemoclaw agent skills, ai coding assistant, cursor, claude code, copilot." license: "Apache-2.0" --- - # NemoClaw Agent Skills for Your AI Coding Assistant -NemoClaw ships agent skills that are generated directly from this documentation. -Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context. -This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately. - -Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation. -Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference. - -**Note:** - -If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root. -Open the `NemoClaw` directory in your coding assistant and the skills load automatically. -This page is for users who installed NemoClaw with the installer and do not have a local clone. - -## Get the Skills - -Fetch only the skills from the NemoClaw repository without downloading the full source tree. - -```bash -git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git -cd NemoClaw -git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md' -git checkout -``` - -Open the `NemoClaw` directory in your AI coding assistant. -The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance. - -You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects. -The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere. - -## Update the Skills - -The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree. -Run `git pull` after each NemoClaw release to pick up new and updated skills. - -## Available Skills - -The following user skills ship with NemoClaw. - -| Skill | Summary | -|-------|---------| -| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. | -| `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. | -| `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). | -| `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). | -| `nemoclaw-user-monitor-sandbox` | Check sandbox health, read logs, and trace agent behavior to diagnose problems. | -| `nemoclaw-user-deploy-remote` | Deploy NemoClaw to a remote GPU instance, set up the Telegram bridge, and review sandbox container hardening. | -| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. | -| `nemoclaw-user-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. | -| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. | - -## Example Questions and Triggered Skills - -After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language. -The assistant matches your question to the relevant skill and follows the guidance it contains. - -Examples of questions your assistant can answer with these skills: - -| Question | Skill triggered | -|----------|-----------------| -| "How do I install NemoClaw?" | `nemoclaw-user-get-started` | -| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` | -| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` | -| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` | -| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` | -| "What security controls can I configure?" | `nemoclaw-user-configure-security` | -| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` | -| "What CLI commands are available?" | `nemoclaw-user-reference` | - -You can also reference a skill directly by name if you know which one you need. - -## AI Coding Assistants that You Can Use with NemoClaw Skills - -The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). -The following table shows how each AI coding assistant can use the NemoClaw skills. +## References -| Assistant | Skill discovery | -|-----------|----------------| -| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. | -| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. | -| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. | +- **Load [references/agent-skills.md](references/agent-skills.md)** when users ask about AI agent support, coding assistant integration, or the .agents/skills/ directory. Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. diff --git a/skills/nemoclaw-user-agent-skills/references/agent-skills.md b/skills/nemoclaw-user-agent-skills/references/agent-skills.md new file mode 100644 index 0000000000..cf2f6e95ea --- /dev/null +++ b/skills/nemoclaw-user-agent-skills/references/agent-skills.md @@ -0,0 +1,83 @@ +# NemoClaw Agent Skills for Your AI Coding Assistant + +NemoClaw ships agent skills that are generated directly from this documentation. +Each skill is a converted version of one or more doc pages, structured so AI coding assistants can consume it as context. +This means you can interact with the full NemoClaw documentation as skills inside your agent chat session, instead of reading the docs separately. + +Ask your assistant a question about NemoClaw and it responds with the same guidance found in these docs, adapted to your current situation. +Skills cover installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, and the CLI reference. + +**Note:** + +If you are a contributor and have cloned the full NemoClaw repository, the full set of skills including contributor and maintainer skills are already available at the project root. +Open the `NemoClaw` directory in your coding assistant and the skills load automatically. +This page is for users who installed NemoClaw with the installer and do not have a local clone. + +## Get the Skills + +Fetch only the skills from the NemoClaw repository without downloading the full source tree. + +```console +$ git clone --filter=blob:none --no-checkout https://github.com/NVIDIA/NemoClaw.git +$ cd NemoClaw +$ git sparse-checkout set --no-cone '/.agents/skills/nemoclaw-user-*/**' '/.agents/skills/nemoclaw-skills-guide/**' '/.claude/**' '/AGENTS.md' '/CLAUDE.md' +$ git checkout +``` + +Open the `NemoClaw` directory in your AI coding assistant. +The assistant discovers the skills in `.agents/skills/` and uses them to answer NemoClaw questions with project-specific guidance. + +You can keep the skills inside the cloned directory or copy `.agents/skills/` to a global location (such as `~/.cursor/skills/` or `~/.claude/skills/`) so they are available across all your projects. +The choice depends on whether you want NemoClaw skills scoped to one workspace or accessible everywhere. + +## Update the Skills + +The sparse checkout filter is saved, so `git pull` fetches only updated skills without downloading the full source tree. +Run `git pull` after each NemoClaw release to pick up new and updated skills. + +## Available Skills + +The following user skills ship with NemoClaw. + +| Skill | Summary | +|-------|---------| +| `nemoclaw-user-overview` | What NemoClaw is, ecosystem placement (OpenClaw + OpenShell + NemoClaw), how it works internally, and release notes. | +| `nemoclaw-user-get-started` | Install NemoClaw, launch a sandbox, and run the first agent prompt. | +| `nemoclaw-user-configure-inference` | Choose inference providers during onboarding, switch models without restarting, and set up local inference servers (Ollama, vLLM, TensorRT-LLM, NIM). | +| `nemoclaw-user-manage-policy` | Approve or deny blocked egress requests in the TUI and customize the sandbox network policy (add, remove, or modify allowed endpoints). | +| `nemoclaw-user-monitor-sandbox` | Check sandbox health, read logs, and trace agent behavior to diagnose problems. | +| `nemoclaw-user-deploy-remote` | Deploy NemoClaw to a remote GPU instance, set up the Telegram bridge, and review sandbox container hardening. | +| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. | +| `nemoclaw-user-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. | +| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. | + +## Example Questions and Triggered Skills + +After opening the cloned repository in your coding assistant, ask a NemoClaw question in natural language. +The assistant matches your question to the relevant skill and follows the guidance it contains. + +Examples of questions your assistant can answer with these skills: + +| Question | Skill triggered | +|----------|-----------------| +| "How do I install NemoClaw?" | `nemoclaw-user-get-started` | +| "Switch my inference provider to Ollama." | `nemoclaw-user-configure-inference` | +| "A network request was blocked. How do I approve it?" | `nemoclaw-user-manage-policy` | +| "Show me the sandbox logs." | `nemoclaw-user-monitor-sandbox` | +| "How do I deploy NemoClaw to a remote GPU?" | `nemoclaw-user-deploy-remote` | +| "What security controls can I configure?" | `nemoclaw-user-configure-security` | +| "Back up my agent workspace files." | `nemoclaw-user-manage-sandboxes` | +| "What CLI commands are available?" | `nemoclaw-user-reference` | + +You can also reference a skill directly by name if you know which one you need. + +## AI Coding Assistants that You Can Use with NemoClaw Skills + +The NemoClaw agent skills follow the [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) and the [Claude Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). +The following table shows how each AI coding assistant can use the NemoClaw skills. + +| Assistant | Skill discovery | +|-----------|----------------| +| Cursor | Reads `AGENTS.md` at the project root, which references `.agents/skills/`. | +| Claude Code | Follows the `.claude/skills/` symlink, which points to `.agents/skills/`. | +| Other assistants | Point the assistant to `.agents/skills/` if it supports project-level skill loading. | diff --git a/skills/nemoclaw-user-configure-inference/SKILL.md b/skills/nemoclaw-user-configure-inference/SKILL.md index 500792a4cf..0a0d57e2ae 100644 --- a/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/skills/nemoclaw-user-configure-inference/SKILL.md @@ -1,9 +1,12 @@ --- name: "nemoclaw-user-configure-inference" -description: "Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui." +description: "Connects NemoClaw to a local inference server. Use when setting up Ollama, vLLM, TensorRT-LLM, NIM, or any OpenAI-compatible local model server with NemoClaw. Trigger keywords - nemoclaw local inference, ollama nemoclaw, vllm nemoclaw, local model server, openai compatible endpoint, switch nemoclaw inference model, change inference runtime, nemoclaw additional model, nemoclaw sub-agent model, openclaw sub-agent, agents.list, sessions_spawn, vlm-demo, nemoclaw tool calling, ollama tool calls, vllm tool-call-parser, raw json in tui, nemoclaw inference options, nemoclaw onboarding providers, nemoclaw inference routing." license: "Apache-2.0" --- + + + # Use a Local Inference Server ## Gotchas @@ -12,14 +15,9 @@ license: "Apache-2.0" ## Prerequisites - - -- 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. +- NemoClaw installed. - 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. @@ -30,14 +28,13 @@ OpenShell intercepts inference traffic and forwards it to the local endpoint you ## Ollama Ollama is the default local inference option. -The onboard wizard detects Ollama automatically when you have installed it or started it on the host. +The onboard wizard detects Ollama automatically when it is installed or running on the host. -If you installed Ollama but have not started it, NemoClaw starts it for you. +If Ollama is installed but not running, NemoClaw starts it for you. On macOS and Linux, the wizard can also offer to install Ollama when it is not present. When the host Ollama is below the minimum version NemoClaw expects for its starter models (currently `0.7.0`), the wizard surfaces an explicit **Upgrade Ollama** entry in the provider menu instead of silently reusing the older daemon, and the express setup path resolves to that entry. The wizard inspects both the CLI binary (`ollama --version`) and the locally running daemon (`/api/version` on `:11434`) so the upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon. -The gate skips Windows-host Ollama reached from WSL through `host.docker.internal`. -The separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side. +The gate skips Windows-host Ollama reached from WSL via `host.docker.internal`; the separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side. On macOS, the wizard runs the platform install or upgrade path with `brew upgrade ollama`. On Linux, the wizard runs the official `https://ollama.com/install.sh` path. Upgrades on Linux always take the sudo-driven system path because the sudo-free user-local fallback would leave the existing system daemon on `:11434` serving the stale binary. @@ -48,7 +45,7 @@ On WSL, the wizard can use, start, restart, or install Ollama on the Windows hos ### Linux Install Modes -On native Linux, the install path picks between a system install (under `/usr/local`, using the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`). +On native Linux, the install path picks between a system install (under `/usr/local`, via the official `https://ollama.com/install.sh`) and a sudo-free user-local install (under `${HOME}/.local`). NemoClaw selects the mode automatically: - Running as root or with passwordless sudo (`sudo -n true` returns 0) selects the system install. @@ -59,23 +56,21 @@ NemoClaw selects the mode automatically: Override the detection with `NEMOCLAW_OLLAMA_INSTALL_MODE=system` or `NEMOCLAW_OLLAMA_INSTALL_MODE=user`. The user-local install replicates only the binary extraction step of the official installer. -It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` one time. -It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so you must relaunch the daemon manually after a reboot. +It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` once. +It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so the daemon must be relaunched manually after a reboot. NemoClaw also prints a one-line `PATH` hint if `${HOME}/.local/bin` is not already on your `PATH`; you can add `export PATH="${HOME}/.local/bin:$PATH"` to your shell profile to invoke `ollama` directly. Both modes rely on `zstd` for archive extraction. On Debian and Ubuntu, the system path uses `sudo apt-get` to install `zstd` automatically and explains the prompt before continuing. -The user-local path cannot bootstrap system packages without elevation. -If `zstd` is missing, it prints per-distro install hints and exits. -Install `zstd` manually, then rerun onboarding. +The user-local path cannot bootstrap system packages without elevation, so if `zstd` is missing it prints per-distro install hints and exits — install `zstd` manually, then rerun onboarding. Run the onboard wizard. -```bash -nemoclaw onboard +```console +$ nemoclaw onboard ``` Select **Local Ollama** from the provider list. -NemoClaw lists installed models or offers starter models if you have not installed any. +NemoClaw lists installed models or offers starter models if none are installed. On hosts where the larger starter models fit the currently available GPU memory, the starter list includes `qwen3.6:35b` and selects it by default. When another GPU workload is using most of the memory at onboard time, NemoClaw downgrades the menu to the largest model that still fits. It pulls the selected model, loads it into memory, and validates it before continuing. @@ -83,7 +78,6 @@ When Ollama reports a loaded-model context length, NemoClaw uses that value for If the selected model declares that it does not support tool calling, onboarding stops with guidance to choose a model whose `ollama show ` capabilities include `tools`. The validation also requires structured chat-completions tool calls. If the model leaks tool-call JSON as plain message text, onboarding stops so you can choose a model that returns tool calls in the expected response field. -If a host-side validation probe times out, NemoClaw retries the Ollama tool-call validation with a larger timeout before failing the setup. On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.internal:11434` and pulls missing models through the Ollama HTTP API instead of requiring the `ollama` CLI inside WSL. ### WSL with Windows-Host Ollama @@ -91,8 +85,8 @@ On WSL, if you choose the Windows-host Ollama path, NemoClaw uses `host.docker.i When NemoClaw runs inside WSL, the provider menu can include Windows-host Ollama actions: - Use Ollama on Windows host when the Windows daemon is already reachable. -- Restart Ollama on Windows host when you installed the daemon but bound it only to Windows loopback. -- Start Ollama on Windows host when you installed Ollama but have not started it. +- Restart Ollama on Windows host when the daemon is installed but only bound to Windows loopback. +- Start Ollama on Windows host when Ollama is installed but not running. - Install Ollama on Windows host when Windows does not have Ollama installed. The install and restart paths set `OLLAMA_HOST=0.0.0.0:11434` on the Windows side so Docker and WSL can reach the daemon through `host.docker.internal`. @@ -102,11 +96,6 @@ If the HTTP endpoint is not reachable yet, NemoClaw also checks for the Windows If the daemon does not become reachable, onboarding prints PowerShell commands you can run to inspect the Windows-side process and port state. Use one Ollama instance on port `11434` at a time. If both WSL and Windows-host Ollama are running, pick the intended menu entry during onboarding so NemoClaw validates and pulls models against the right daemon. -Windows-host Ollama requires Docker Desktop WSL integration because the sandbox reaches the Windows daemon through Docker Desktop's WSL routing path. -If NemoClaw detects native Docker Engine inside WSL, the provider menu labels Windows-host Ollama actions as requiring Docker Desktop integration. -Selecting one of those actions in the unsupported native Docker topology exits early with a remediation message instead of trying to start or install Ollama on Windows. - - **Warning:** Ollama is convenient for local chat, but some model/template combinations can @@ -114,13 +103,13 @@ return tool calls as plain text under realistic agent load. If the TUI shows raw JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a tool, switch to vLLM with `--enable-auto-tool-choice` and the correct `--tool-call-parser`. See [Tool-Calling Reliability](references/tool-calling-reliability.md). - ### Authenticated Reverse Proxy On non-WSL hosts, NemoClaw keeps Ollama bound to `127.0.0.1:11434` and starts a token-gated reverse proxy on `0.0.0.0:11435`. The native install/start paths also reset NemoClaw-managed systemd launches to the loopback binding. -Containers and other hosts on the local network reach Ollama only through the proxy, which validates a Bearer token before forwarding requests. +Containers and other hosts on the local network reach Ollama only through the +proxy, which validates a Bearer token before forwarding requests. On that native path, NemoClaw never exposes Ollama without authentication. WSL Ollama paths do not use this proxy. @@ -140,19 +129,22 @@ For non-WSL Ollama setups, the onboard wizard manages the proxy automatically: On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge. When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like: -```bash -sudo ufw allow from to any port 11435 proto tcp -nemoclaw onboard +```console +$ sudo ufw allow from to any port 11435 proto tcp +$ nemoclaw onboard ``` If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check. -NemoClaw configures the sandbox provider to use proxy port `11435` with the generated token as its `OPENAI_API_KEY` credential. -OpenShell's L7 proxy injects the token at egress, so the agent inside the sandbox never sees the token directly. +The sandbox provider is configured to use proxy port `11435` with the generated +token as its `OPENAI_API_KEY` credential. +OpenShell's L7 proxy injects the token at egress, so the agent inside the +sandbox never sees the token directly. All proxy endpoints require the Bearer token, including `GET /api/tags`. -Internal health and reachability checks run through the proxy treat any HTTP response, including `401`, as proof the proxy is alive. -They fail only when nothing answers at all. +Internal health and reachability checks run via the proxy treat any HTTP +response (including `401`) as proof the proxy is alive — they only fail +when nothing answers at all. If Ollama is already running on a non-loopback address when you start onboard, the wizard restarts it on `127.0.0.1:11434` so the proxy is the only network @@ -164,82 +156,126 @@ When you switch away from Ollama, stop host services, or destroy an Ollama-backe The cleanup sends `keep_alive: 0` for each model reported by Ollama and runs on a best-effort basis, so shutdown continues if Ollama is already stopped. This does not delete downloaded model files. -### Non-Interactive Setup +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup. -```bash -NEMOCLAW_PROVIDER=ollama \ - NEMOCLAW_MODEL=qwen3.5:9b \ - nemoclaw onboard --non-interactive --yes +## OpenAI-Compatible Server + +This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. +For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. +This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions. +To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard. + +Start your model server. +The examples below use vLLM, but any OpenAI-compatible server works. + +```console +$ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 ``` -If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. -If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. -Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. -In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu. -If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit. -After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly. -When Ollama reports a loaded-model context length below `16384` and `NEMOCLAW_CONTEXT_WINDOW` is unset, NemoClaw raises the baked `contextWindow` to `16384` so the agent prompt and tool definitions fit better than the stock daemon default. -If the initial Ollama validation probe times out during a cold load, NemoClaw retries once with a 300-second probe budget. -This applies beyond DGX Spark, including tight-VRAM dGPU hosts where warm-up can spill from GPU to CPU. - -`--yes` (or `NEMOCLAW_YES=1`) authorizes the Ollama model download without an interactive confirmation prompt. -Under `--non-interactive`, include `--yes` (or `NEMOCLAW_YES=1`) to authorize the download. -Onboard exits otherwise because it cannot prompt. -Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading. - -| Variable | Purpose | -|---|---| -| `NEMOCLAW_PROVIDER` | Set to `ollama`. | -| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | -| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. | +Run the onboard wizard. + +```console +$ nemoclaw onboard +``` -## Compatible Local Servers +When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. +Enter the base URL of your local server, for example `http://localhost:8000/v1`. -Use **Other OpenAI-compatible endpoint** for vLLM, TensorRT-LLM, llama.cpp, LocalAI, NIM, SGLang, or another server that implements `/v1/chat/completions`. -For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default because some local backends accept `/v1/responses` but drop system prompts or tool definitions. -Set `NEMOCLAW_PREFERRED_API=openai-responses` only after you have verified that the backend streams the events OpenClaw requires. +The wizard prompts for an API key. +If your server does not require authentication, enter any non-empty string (for example, `dummy`). -For the full compatible-endpoint prompt flow, non-interactive variables, API-path controls, managed vLLM profiles, NIM setup, and timeout settings, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers). +NemoClaw validates the endpoint by sending a test inference request before continuing. +The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider. +If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires. +If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget. +Route, configuration, and authentication failures still fail immediately. -## Managed vLLM and NIM +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup, Selecting the API Path. -NemoClaw can use an already-running vLLM server on `localhost:8000`, start managed vLLM on supported NVIDIA GPU hosts, or manage a local NIM container when `NEMOCLAW_EXPERIMENTAL=1` is set. -Managed vLLM records the model returned by `/v1/models` and uses runtime metadata such as `max_model_len` when available. -NIM uses the same chat-completions API path restriction as vLLM. +## Anthropic-Compatible Server -For registry slugs, Hugging Face token requirements, NGC login behavior, and non-interactive examples, refer to [Inference Options](references/inference-options.md#setup-details-for-local-and-compatible-providers). +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. -## Verify the Configuration +## vLLM -After onboarding completes, confirm the active provider and model. +When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. +On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. -```bash -nemoclaw status +For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. + +```console +$ nemoclaw onboard ``` -The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. -For Local Ollama, status also checks the authenticated proxy when a proxy token is available. -If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use. +If vLLM is already running, NemoClaw detects the running model and validates the endpoint. +If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. +Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. +NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, and prints progress markers while the model loads. +The first run can take 10 to 30 minutes. +Later runs reuse the cached image and model weights. -## Switch Models at Runtime +Managed vLLM uses these profiles: + +| Host profile | Default model | +|---|---| +| DGX Spark | `Qwen/Qwen3.6-27B-FP8` | +| DGX Station | `Qwen/Qwen3.6-27B-FP8` | +| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | -You can change the model without re-running onboard. -Refer to [Switch Inference Models](references/switch-inference-providers.md) for the full procedure. +**Note:** -For compatible endpoints, the command is: +NemoClaw forces the `chat/completions` API path for vLLM. +The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. -```bash -nemoclaw inference set --provider compatible-endpoint --model +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup, Override the Managed-vLLM Model. + +## NVIDIA NIM (Experimental) + +NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. + +Set the experimental flag and run onboard. + +```console +$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard ``` -If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. +Select **Local NVIDIA NIM [experimental]** from the provider list. +NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. +On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. + +NIM container images are hosted on `nvcr.io` and require NGC registry authentication before `docker pull` succeeds. +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 once 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 the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines. + +**Note:** + +NIM uses vLLM internally. +The same `chat/completions` API path restriction applies. + +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps on Non-Interactive Setup. + +## Timeout Configuration + +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. + +## Verify the Configuration + +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. + +## Switch Models at Runtime + +Load [references/use-local-inference-details.md](references/use-local-inference-details.md) for detailed steps. ## References - **Load [references/switch-inference-providers.md](references/switch-inference-providers.md)** when switching inference providers, changing the model runtime, or reconfiguring inference routing. Changes the active inference model without restarting the sandbox. - **Load [references/set-up-sub-agent.md](references/set-up-sub-agent.md)** when users ask how to add a second model, configure a sub-agent model, use Omni for vision tasks, configure agents.list, or use sessions_spawn in NemoClaw. Shows the NemoClaw-specific file paths and update flow for adding an auxiliary OpenClaw sub-agent model. +- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when vLLM with a tool-call parser is recommended, and how to repoint NemoClaw to a parser-aware local endpoint. - **Load [references/inference-options.md](references/inference-options.md)** when explaining which providers are available, what the onboard wizard presents, or how inference routing works. Lists all inference providers offered during NemoClaw onboarding. -- **[references/tool-calling-reliability.md](references/tool-calling-reliability.md)** — Explains Ollama tool-call leak symptoms, when to use vLLM with a tool-call parser, and how to repoint NemoClaw to a parser-aware local endpoint. +- **Load [references/use-local-inference-details.md](references/use-local-inference-details.md)** when you need detailed steps for Non-Interactive Setup, Selecting the API Path, Anthropic-Compatible Server, and related details. ## Related Skills diff --git a/skills/nemoclaw-user-configure-inference/references/inference-options.md b/skills/nemoclaw-user-configure-inference/references/inference-options.md index 8af6e446af..5242cff46c 100644 --- a/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -1,20 +1,10 @@ + + # NemoClaw Inference Options -import { AgentOnly } from "../_components/AgentGuide"; - NemoClaw supports multiple inference providers. -During onboarding, the NemoClaw onboarding wizard presents a numbered list of providers to choose from. -Your selection determines where NemoClaw routes the agent's inference traffic. - - -For OpenClaw onboarding, use `nemoclaw onboard`. -The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent. - - - -For Hermes onboarding, use `nemoclaw onboard`. -The provider flow is the same, with the Hermes Provider route available for Hermes Agent. - +During onboarding, the `nemoclaw onboard` wizard presents a numbered list of providers to choose from. +Your selection determines where the agent's inference traffic is routed. ## How Inference Routing Works @@ -47,13 +37,13 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l The onboard wizard presents the following provider options by default. The first six are always available. -Ollama appears when you have installed or started it on the host. +Ollama appears when it is installed or running on the host. Local vLLM appears when NemoClaw detects a running vLLM server. The managed install/start vLLM entry appears by default on DGX Spark and DGX Station, and appears on generic Linux NVIDIA GPU hosts after opt-in. | 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_API_KEY`. | Nemotron 3 Super 120B, 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` | @@ -67,7 +57,7 @@ The managed install/start vLLM entry appears by default on DGX Spark and DGX Sta NVIDIA Nemotron models expose OpenAI-compatible APIs across every supported deployment surface, so two onboarding options can route to Nemotron. -| Nemotron Host | Onboard Wizard Option | Why | +| Where Nemotron is hosted | Onboard wizard option | Why | |---|---|---| | `build.nvidia.com` (NVIDIA-hosted) | **Option 1: NVIDIA Endpoints** | NemoClaw sets the base URL to `https://integrate.api.nvidia.com/v1` for you and validates the model against the build catalog. | | Self-hosted NIM container | **Option 3: Other OpenAI-compatible endpoint** | NIM exposes an OpenAI-compatible `/v1/chat/completions` route. Point the base URL at your NIM service and enter the Nemotron model ID. | @@ -84,53 +74,14 @@ When you select it, NemoClaw starts the router proxy on the host, waits for its The sandbox does not call the router port directly. The router model pool lives in `nemoclaw-blueprint/router/pool-config.yaml`. -Edit that file to define which models the router can choose from. The default pool routes between NVIDIA-hosted Nemotron models and uses the `tolerance` value to choose the lowest-cost model whose predicted quality stays within the configured threshold. - -```yaml -routing: - method: prefill - checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt - tolerance: 0.20 - encoder: Qwen/Qwen3.5-0.8B - -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" - - - name: super - litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3" - cost_per_m_input_tokens: 0.10 - api_base: "https://inference-api.nvidia.com" -``` - -The `tolerance` parameter controls the accuracy-cost tradeoff. - -| Value | Behavior | -|-------|----------| -| `0.0` | Always pick the most accurate model. | -| `0.20` | Allow up to 20 percentage points below the best for a cheaper model (default). | -| `1.0` | Always pick the cheapest model. | - -The router runs on the host, not inside the sandbox. - -```text -Sandbox (agent) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API - └── PrefillRouter selects model -``` - -Credentials flow through the OpenShell provider system. -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 +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive ``` -### Host Python Requirement +### Host Python requirement The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding. NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of: @@ -143,19 +94,18 @@ This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`: -```bash -NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard +```console +$ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard ``` The pin is strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`. -NemoClaw rejects relative command names such as `python3.12`. -Use `command -v python3.12` to find the absolute path. +Relative command names such as `python3.12` are rejected; use `command -v python3.12` to find the absolute path. If `python -m venv` itself fails for a probe-clean interpreter (for example, a corrupt ensurepip seed), NemoClaw retries with the next healthy candidate when no pin is set; with a pin set, the failure stops onboarding so you can fix or repoint the pinned python. ## Caveated Local Options -The following local inference options have caveats. +The following local inference options are caveated. Local NIM and generic Linux managed vLLM install/start require `NEMOCLAW_EXPERIMENTAL=1`; DGX Spark and DGX Station managed vLLM entries appear by default. An already-running vLLM server appears directly in the onboarding selection list. @@ -170,268 +120,23 @@ 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. +Transient upstream validation failures are retried before the wizard reports a provider failure. The `nvapi-` prefix check applies only to `NVIDIA_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 | |---|---| | OpenAI | Tries `/responses` first, then `/chat/completions`. | -| NVIDIA Endpoints | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). | -| Google Gemini | Validates through Gemini's OpenAI-compatible chat-completions path only; NemoClaw skips the `/v1/responses` probe because Gemini does not support the Responses API. | +| NVIDIA Endpoints | Validates via `/v1/chat/completions` only; the `/v1/responses` probe is skipped because NVIDIA Build does not expose `/v1/responses` (returns 404 for every model). | +| Google Gemini | Validates via Gemini's OpenAI-compatible chat-completions path only; the `/v1/responses` probe is skipped because Gemini does not support the Responses API. | | Other OpenAI-compatible endpoint | Tries `/v1/responses` first with a tool-calling probe; falls back to `/v1/chat/completions`. Selected runtime API defaults to `/v1/chat/completions`; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. | | Anthropic-compatible | Tries `/v1/messages`. | | NVIDIA Endpoints (manual model entry) | Validates the model name against the catalog API. | | Compatible endpoints | Sends a real inference request because many proxies do not expose a `/models` endpoint. For OpenAI-compatible endpoints, the probe tries `/v1/responses` first then falls back to `/v1/chat/completions`; the selected runtime API defaults to `/v1/chat/completions`. Set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` at runtime when validation succeeds. | -| Local NVIDIA NIM | Validates through `/v1/chat/completions` only; NemoClaw skips the `/v1/responses` probe (same as NVIDIA Endpoints). | - -## Setup Details for Local and Compatible Providers - -The sections below collect the detailed setup prompts and environment variables for local and compatible inference providers. -Use them when the quickstart or local inference guide points you here for exact command shapes. - -## OpenAI-Compatible Server - -This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others. -For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default. -This avoids a class of failures where local backends accept `/v1/responses` requests but silently drop the system prompt and tool definitions. -To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API=openai-responses` before running onboard. - -Start your model server. -The examples below use vLLM, but any OpenAI-compatible server works. - -```bash -vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 -``` - -Run the onboard wizard. - -```bash -nemoclaw onboard -``` - -When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. -Enter the base URL of your local server, for example `http://localhost:8000/v1`. - -The wizard prompts for an API key. -If your server does not require authentication, enter any non-empty string (for example, `dummy`). - -NemoClaw validates the endpoint by sending a test inference request before continuing. -The wizard probes `/v1/chat/completions` by default for the compatible-endpoint provider. -If you set `NEMOCLAW_PREFERRED_API=openai-responses`, NemoClaw probes `/v1/responses` instead and only selects it when the response includes the streaming events OpenClaw requires. -If a reasoning model returns only reasoning content before producing a final answer, NemoClaw retries the smoke request with a larger response budget. -Route, configuration, and authentication failures still fail immediately. - -### Non-Interactive Setup - -Set the following environment variables for scripted or CI/CD deployments. - -```bash -NEMOCLAW_PROVIDER=custom \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ - NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ - COMPATIBLE_API_KEY=dummy \ - nemoclaw onboard --non-interactive -``` - -| Variable | Purpose | -|---|---| -| `NEMOCLAW_PROVIDER` | Set to `custom` for an OpenAI-compatible endpoint. | -| `NEMOCLAW_ENDPOINT_URL` | Base URL of the local server. | -| `NEMOCLAW_MODEL` | Model ID as reported by the server. | -| `COMPATIBLE_API_KEY` | API key for the endpoint. Use any non-empty value if authentication is not required. | - -### Selecting the API Path - -For the compatible-endpoint provider, `/v1/chat/completions` is the default. -NemoClaw tests streaming events during onboarding and uses chat completions -without probing the Responses API. - -To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: - -```bash -NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard -``` - -The wizard then probes `/v1/responses` and only selects it when streaming -support is complete. -If the probe fails, the wizard falls back to `/v1/chat/completions` -automatically. -You can use this variable in both interactive and non-interactive mode. - -| Variable | Values | Default | -|---|---|---| -| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | - -If you already onboarded and the sandbox is failing at runtime, re-run `nemoclaw onboard` to re-probe the endpoint and bake the correct API path -into the image. -Refer to [Switch Inference Models](switch-inference-providers.md) for more information. - -## Anthropic-Compatible Server - -If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. - -```bash -nemoclaw onboard -``` - -For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. - -```bash -NEMOCLAW_PROVIDER=anthropicCompatible \ - NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ - NEMOCLAW_MODEL=my-model \ - COMPATIBLE_ANTHROPIC_API_KEY=dummy \ - nemoclaw onboard --non-interactive -``` - -## vLLM - -When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. -On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. - -For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. - -If vLLM is already running, NemoClaw detects the running model and validates the endpoint. -When vLLM exposes runtime metadata such as `max_model_len`, NemoClaw uses that value for the `contextWindow` baked into `openclaw.json` unless you set `NEMOCLAW_CONTEXT_WINDOW` yourself. -If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. -Generic Linux NVIDIA GPU hosts still require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` before the managed entry appears. -NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready. -Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image. -If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. -If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting. -The first run can take 10 to 30 minutes. -Later runs reuse the cached image and model weights. - -Managed vLLM uses these profiles: - -| Host profile | Default model | -|---|---| -| DGX Spark | `nvidia/Qwen3.6-35B-A3B-NVFP4` | -| DGX Station | `deepseek-ai/DeepSeek-V4-Flash` | -| Linux with an NVIDIA GPU | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | - -**Note:** - -NemoClaw forces the `chat/completions` API path for vLLM. -The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool calls arrive as raw text. - -### Non-Interactive Setup - -Use an already-running vLLM server: - -```bash -NEMOCLAW_PROVIDER=vllm \ - nemoclaw onboard --non-interactive -``` - -Install or start managed vLLM when NemoClaw detects a supported profile. -On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts. - -```bash -NEMOCLAW_PROVIDER=install-vllm \ - nemoclaw onboard --non-interactive -``` - -NemoClaw records the model returned by vLLM's `/v1/models` endpoint. -Start vLLM with the model you want before onboarding if you manage the server yourself. - -### Override the Managed-vLLM Model - -Managed vLLM serves the profile default unless you select a different registry entry. -Export `NEMOCLAW_VLLM_MODEL=` before invoking the installer to choose a different model from the registry. -NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`. -Recognized slugs are: - -| Slug | Hugging Face model | Notes | -|---|---|---| -| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash` | Default on the DGX Station profile | -| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Supported override | -| `qwen3.6-35b-a3b-nvfp4` | `nvidia/Qwen3.6-35B-A3B-NVFP4` | Default on the DGX Spark profile | -| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile | -| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance | - -The slug is case-insensitive; the full Hugging Face id is also accepted. -An unrecognized value fails fast with a list of valid slugs. - -Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container: - -```bash -export HF_TOKEN= -NEMOCLAW_PROVIDER=install-vllm \ - NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ - nemoclaw onboard --non-interactive -``` - -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. - -## NVIDIA NIM (Experimental) - -NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU. - -Set the experimental flag and run onboard. - -```bash -NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard -``` - -Select **Local NVIDIA NIM [experimental]** from the provider list. -NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. -On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected GPU model and the total VRAM so you can confirm which device class the model selection used. -On Docker 29.x or containerd image-store hosts, NemoClaw resolves the host-platform manifest digest before pulling multi-architecture NIM images when the registry exposes an index. -It pulls `repo@digest` and retags the local image so NGC attestation metadata on other architectures does not block the selected platform. -If the registry does not expose a matching index, NemoClaw falls back to the tag pull. - -NVIDIA hosts NIM container images on `nvcr.io`, and `docker pull` requires NGC registry authentication. -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 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. - -**Note:** - -NIM uses vLLM internally. -The same `chat/completions` API path restriction applies. - -## Timeout Configuration - -Local inference requests use a default timeout of 180 seconds. -Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup. - -To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: - -```bash -export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -nemoclaw onboard -``` - -The value is in seconds. -NemoClaw bakes this setting into the sandbox at build time. -Changing it after onboarding requires re-running `nemoclaw onboard`. - -`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe. -During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure. -NemoClaw also retries Docker runtime detection with a longer `docker info` timeout before it chooses the local inference route. -The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds. -On hosts where the sandbox image takes minutes to build or upload, raise both settings together. -Examples include large quantized models, DGX Station first runs, and remote VMs over a slow link. - -```bash -export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 -export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemoclaw onboard -``` - -If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). +| Local NVIDIA NIM | Validates via `/v1/chat/completions` only; the `/v1/responses` probe is skipped (same as NVIDIA Endpoints). | ## Next Steps - [Use a Local Inference Server](../SKILL.md) for Ollama, vLLM, NIM, and compatible-endpoint setup details. - - [Tool-Calling Reliability](tool-calling-reliability.md) for deciding when Ollama is enough and when vLLM with a parser is safer. - - [Switch Inference Models](switch-inference-providers.md) for changing the model at runtime without re-onboarding. diff --git a/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md b/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md index 48cf9b38c4..148eaf0e7e 100644 --- a/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md +++ b/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md @@ -1,3 +1,5 @@ + + # Set Up Task-Specific Sub-Agents OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents). @@ -35,17 +37,17 @@ It keeps the primary `main` agent on the normal NemoClaw inference route and add | Sub-agent model | `nvidia-omni/private/nvidia/nemotron-3-nano-omni-reasoning-30b-a3b` | | Delegation tool | `sessions_spawn` | -The sub-agent uses Omni as the specialist model for image tasks. +Omni is used as the specialist model for image tasks. The primary orchestration model remains responsible for conversation, planning, and deciding when to delegate. ## 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. -```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 +```console +$ 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 ``` Create `/tmp/openclaw.updated.json` with the OpenClaw sub-agent config. @@ -54,13 +56,13 @@ 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. -```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 +```console +$ 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 ``` Check `/tmp/gateway.log` after upload and confirm the gateway hot-reloaded the provider or `agents.list` change. @@ -75,10 +77,10 @@ For the Omni example: ``` Use the same provider ID that appears in `models.providers`, such as `nvidia-omni`. -After uploading the auth profile, make sure the sandbox user owns the sub-agent directory: +After uploading the auth profile, make sure the sub-agent directory is owned by the sandbox user: -```bash -docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator +```console +$ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator ``` ## Allow Auxiliary Provider Egress diff --git a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md index 0a7a9b6d55..c5a623c42e 100644 --- a/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md +++ b/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md @@ -1,9 +1,9 @@ + + # Switch Inference Models at Runtime -import { AgentOnly } from "../_components/AgentGuide"; - Change the active inference model while the sandbox is running. -You do not need to restart the sandbox. +No restart is required. ## Prerequisites @@ -12,132 +12,100 @@ You do not need to restart the sandbox. ## Switch to a Different Model - Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace. - - -Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. -The command updates the OpenShell inference route and synchronizes the running agent config. -For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes. -Pass `--sandbox ` when you do not want to use the default registered sandbox. -Under `nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. - +For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes. - Pass `--sandbox ` when you do not want to use the default registered sandbox. - +Under `nemohermes`, pass `--sandbox ` when more than one Hermes sandbox is registered. ### NVIDIA Endpoints -```bash -nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +```console +$ nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` ### OpenAI -```bash -nemoclaw inference set --provider openai-api --model gpt-5.4 +```console +$ nemoclaw inference set --provider openai-api --model gpt-5.4 ``` ### Anthropic -```bash -nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 +```console +$ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 ``` ### Google Gemini -```bash -nemoclaw inference set --provider gemini-api --model gemini-2.5-flash +```console +$ nemoclaw inference set --provider gemini-api --model gemini-2.5-flash ``` ### Compatible Endpoints If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: -```bash -nemoclaw inference set --provider compatible-endpoint --model +```console +$ nemoclaw inference set --provider compatible-endpoint --model ``` -```bash -nemoclaw inference set --provider compatible-anthropic-endpoint --model +```console +$ nemoclaw inference set --provider compatible-anthropic-endpoint --model ``` - - ### Hermes Provider For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered Hermes Provider route: -```bash -nemoclaw inference set --provider hermes-provider --model openai/gpt-5.4-mini +```console +$ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini ``` - - -### API Family Sync - -Before patching the in-sandbox config, NemoClaw resolves the target route's API family: OpenAI chat completions, Anthropic Messages, or OpenAI Responses. -For OpenClaw, `inference set` syncs the provider API family and primary model reference into the running config. -For Hermes, `inference set` writes `model.api_mode: anthropic_messages` for Anthropic Messages routes, `model.api_mode: codex_responses` for OpenAI Responses routes, and removes `api_mode` for OpenAI-style chat-completions routes. -Hermes also keeps `model.api_key` on the OpenShell proxy placeholder so dashboard and API sessions continue to authenticate through the gateway after a route change. - -Amazon Bedrock Runtime routes created through `compatible-anthropic-endpoint` are the exception. -When you switch within the same Bedrock Runtime compatible provider, NemoClaw keeps the route OpenAI-compatible and does not set Hermes to Anthropic Messages mode. - #### Switching from Responses API to Chat Completions -If onboarding selected `/v1/responses` but the agent fails at runtime, re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image. -This can happen when the backend does not emit the streaming events OpenClaw requires. +If onboarding selected `/v1/responses` but the agent fails at runtime (for +example, because the backend does not emit the streaming events OpenClaw +requires), re-run onboarding so the wizard re-probes the endpoint and bakes +the correct API path into the image: -```bash -nemoclaw onboard +```console +$ nemoclaw onboard ``` Select the same provider and endpoint again. -The updated streaming probe detects incomplete `/v1/responses` support and selects `/v1/chat/completions` automatically. +The updated streaming probe will detect incomplete `/v1/responses` support +and select `/v1/chat/completions` automatically. -For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by default, so you do not need an environment variable to keep the safe path. -To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding: +For the compatible-endpoint provider, NemoClaw uses `/v1/chat/completions` by +default, so no env var is required to keep the safe path. +To opt in to `/v1/responses` for a backend you have verified end to end, set +`NEMOCLAW_PREFERRED_API` before onboarding: -```bash -NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +```console +$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard ``` **Note:** -`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image. -If you recreate the sandbox without the override environment variable, the image reverts to the original API path. +`NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but +does not update the Dockerfile ARG baked into the image. +If you recreate the sandbox without the override env var, the image reverts to +the original API path. A fresh `nemoclaw onboard` is the reliable fix because it updates both the session and the baked image. ## Cross-Provider Switching - Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`. The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config. -If the in-sandbox config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint. -Run the rebuild before relying on the running agent if the warning says the image config could not be patched. -```bash -nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify -``` - - - -Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`. -The command updates both the gateway route and `/sandbox/.hermes/config.yaml`. -If the Hermes config sync fails after the gateway route is updated, NemoClaw keeps the host registry aligned with the gateway and prints a rebuild hint. -Run the rebuild before relying on the running agent if the warning says the image config could not be patched. - -```bash -nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +```console +$ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify ``` - - Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential. ## Tune Model Metadata @@ -154,42 +122,27 @@ To change these values, set the corresponding environment variables before runni | `NEMOCLAW_AGENT_TIMEOUT` | Positive integer (seconds) | `600` | | `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | Go-style duration (`30m`, `1h`, `0m` to disable) | `unset` (OpenClaw default) | -NemoClaw ignores invalid values and bakes the default into the image. +Invalid values are ignored, and the default bakes into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. -For local vLLM, onboarding uses the runtime `max_model_len` value when the server reports one and `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. -During interactive onboarding, NemoClaw prompts for **Text only** or **Text + Image** when the discovered model name looks multimodal and `NEMOCLAW_INFERENCE_INPUTS` is not already valid. -Non-interactive onboarding uses the environment value or the default `text` setting. - -```bash -export NEMOCLAW_CONTEXT_WINDOW=65536 -export NEMOCLAW_MAX_TOKENS=8192 -export NEMOCLAW_REASONING=true -export NEMOCLAW_INFERENCE_INPUTS=text,image -export NEMOCLAW_AGENT_TIMEOUT=1800 -export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m -nemoclaw onboard -``` - - - -`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`. -Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware. -NemoClaw writes this value into `openclaw.json` during onboarding. -The default sandbox can keep that file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. -Rebuild the sandbox with `nemoclaw onboard` to apply a new value. - - - -`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into the Hermes sandbox image. -Increase it for slow local inference, such as CPU-only Ollama or vLLM on modest hardware. -Direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. -Rebuild the sandbox with `nemoclaw onboard` to apply a new value. - - - - +```console +$ export NEMOCLAW_CONTEXT_WINDOW=65536 +$ export NEMOCLAW_MAX_TOKENS=8192 +$ export NEMOCLAW_REASONING=true +$ export NEMOCLAW_INFERENCE_INPUTS=text,image +$ export NEMOCLAW_AGENT_TIMEOUT=1800 +$ export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m +$ nemoclaw onboard +``` + +`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into +`agents.defaults.timeoutSeconds`. Increase it for slow local inference (for +example, CPU-only Ollama or vLLM on modest hardware). NemoClaw writes this +value into `openclaw.json` during onboarding. The default sandbox may keep that +file writable for agent state, but direct in-sandbox edits are not the supported +or durable way to change NemoClaw-managed defaults. Rebuild the sandbox via +`nemoclaw onboard` to apply a new value. `NEMOCLAW_AGENT_HEARTBEAT_EVERY` sets `agents.defaults.heartbeat.every`. This controls OpenClaw's periodic main-session agent turn. @@ -198,22 +151,15 @@ The OpenClaw default is 30 minutes (1 hour for Anthropic OAuth / Claude CLI reus Tune the cadence with a duration string like `5m` or `2h`, or set `0m` to disable the periodic turns entirely. Disabling also drops `HEARTBEAT.md` from normal-run bootstrap context per upstream behavior, so the model no longer sees heartbeat-only instructions. NemoClaw writes this value into `openclaw.json` during onboarding. -The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and a rebuild overwrites direct file edits. -Rebuild the sandbox with `nemoclaw onboard --resume` to apply a new value. - - - - -Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. -Rebuild the sandbox with `nemoclaw onboard --resume` to apply build-time inference metadata changes. - - +The in-sandbox `openclaw config set` command is not the supported path for +NemoClaw-managed build-time defaults, and direct file edits are overwritten by a +rebuild. Rebuild the sandbox via `nemoclaw onboard --resume` to apply a new value. These variables are build-time settings. If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image: -```bash -nemoclaw onboard --resume --recreate-sandbox +```console +$ nemoclaw onboard --resume --recreate-sandbox ``` ## Verify the Active Model @@ -242,33 +188,20 @@ Run `nemoclaw onboard` to configure one. Run the status command when you also need sandbox, service, and messaging health: -```bash -nemoclaw status +```console +$ nemoclaw status ``` The status output includes the active provider, model, and endpoint with the rest of the sandbox state. ## Notes - - - The host keeps provider credentials. - The sandbox continues to use `inference.local`. - `nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash. - Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. - Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. - - - -- The host keeps provider credentials. -- The sandbox continues to use `inference.local`. -- `nemoclaw inference set` patches the selected running Hermes sandbox config and recomputes its config hash. -- Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. -- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. - - - ## Related Topics - [Inference Options](inference-options.md) for the full list of providers available during onboarding. diff --git a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md index 5c13623091..01f2c36115 100644 --- a/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md +++ b/skills/nemoclaw-user-configure-inference/references/tool-calling-reliability.md @@ -1,7 +1,11 @@ + + # Tool-Calling Reliability for Local Inference -Local inference is useful for privacy, cost control, and offline development, but tool-calling agents place stricter demands on the model server than simple chat. -The model server must return structured `tool_calls`, not a JSON-looking string inside normal assistant text. +Local inference is useful for privacy, cost control, and offline development, but +tool-calling agents place stricter demands on the model server than simple chat. +The model server must return structured `tool_calls`, not a JSON-looking string +inside normal assistant text. Use this page when the TUI shows raw JSON such as: @@ -9,7 +13,8 @@ Use this page when the TUI shows raw JSON such as: {"arguments":{"query":"robotics"},"name":"memory_search"} ``` -If that appears as text in the assistant reply, OpenClaw cannot dispatch the tool because the inference response did not include a structured tool call. +If that appears as text in the assistant reply, OpenClaw cannot dispatch the +tool because the inference response did not include a structured tool call. ## Quick Choice Guide @@ -23,8 +28,9 @@ If that appears as text in the assistant reply, OpenClaw cannot dispatch the too | Multi-turn tool dispatch | Risky | Yes | Ollama can work well for lightweight local chat and some simple tool surfaces. -For OpenClaw-style agent loops with multiple tools, long instructions, or multi-turn dispatch, use a server that exposes OpenAI-compatible `/v1/chat/completions` with a tool-call parser. -vLLM is the common local choice. +For OpenClaw-style agent loops with multiple tools, long instructions, or +multi-turn dispatch, use a server that exposes OpenAI-compatible +`/v1/chat/completions` with a tool-call parser. vLLM is the common local choice. ## Symptom @@ -35,23 +41,20 @@ The common failure mode is: - The gateway treats the response as normal text. - No tool runs, and the user sees raw JSON in the TUI. -This is different from a network or policy block. -`nemoclaw status`, `nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while tool dispatch still fails inside the conversation. - -### Nemotron Managed Inference - -For the `nvidia/nemotron-3-super-120b-a12b` managed inference route on `inference.local`, NemoClaw disables OpenClaw's native code-based tool search surface. -That route otherwise tends to generate invalid JavaScript for the `tool_search_code` helper, which creates `[tools] tool_search_code failed` noise even when normal turns succeed. -The agent still uses the structured tool-calling surface that the model handles correctly. +This is different from a network or policy block. `nemoclaw status`, +`nemoclaw logs`, and `nemoclaw debug --quick` can all look healthy while +tool dispatch still fails inside the conversation. ## Recommended Fix -For persistent NemoClaw use, start vLLM with auto tool choice and the parser that matches your model family, then rerun onboarding and select **Local vLLM [experimental]** or **Other OpenAI-compatible endpoint**. +For persistent NemoClaw use, start vLLM with auto tool choice and the parser that +matches your model family, then rerun onboarding and select **Local vLLM +[experimental]** or **Other OpenAI-compatible endpoint**. For Hermes 3 style models, a known-good vLLM command shape is: -```bash -vllm serve /models/Hermes-3-Llama-3.1-8B \ +```console +$ vllm serve /models/Hermes-3-Llama-3.1-8B \ --served-model-name hermes-3-llama-3.1-8b \ --enable-auto-tool-choice \ --tool-call-parser hermes \ @@ -90,20 +93,22 @@ services: Then onboard against that endpoint: -```bash -NEMOCLAW_PROVIDER=custom \ +```console +$ NEMOCLAW_PROVIDER=custom \ NEMOCLAW_ENDPOINT_URL=http://localhost:8002/v1 \ NEMOCLAW_MODEL=hermes-3-llama-3.1-8b \ COMPATIBLE_API_KEY=$VLLM_API_KEY \ nemoclaw onboard --non-interactive ``` -If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any non-empty placeholder, such as `dummy`. +If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any +non-empty placeholder, such as `dummy`. ## Advanced Temporary Repointing -NemoClaw-managed sandboxes normally block direct `openclaw config set` writes inside the sandbox because those edits do not survive rebuilds. -Prefer rerunning `nemoclaw onboard` for a persistent provider change. +NemoClaw-managed sandboxes normally block direct `openclaw config set` writes +inside the sandbox because those edits do not survive rebuilds. Prefer rerunning +`nemoclaw onboard` for a persistent provider change. If you are intentionally testing a mutable OpenClaw config, prepare a batch file like this: @@ -129,13 +134,15 @@ like this: } ``` -Apply it only in environments where OpenClaw allows config writes: +Apply it only in environments where OpenClaw config writes are allowed: -```bash -openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json +```console +$ openclaw config set --batch-file /sandbox/.openclaw/vllm-tool-calls.json ``` -After testing, persist the working provider through `nemoclaw onboard` so the sandbox image, OpenShell inference route, and host-managed credentials stay in sync. +After testing, persist the working provider through `nemoclaw onboard` so the +sandbox image, OpenShell inference route, and host-managed credentials stay in +sync. ## Verify the Fix @@ -143,9 +150,12 @@ After switching to vLLM, ask for an action that should use a tool. Good signs: - The TUI does not show JSON blobs as assistant text. - The gateway log shows tool dispatch and a follow-up answer. -- `nemoclaw status` reports the local vLLM or compatible endpoint as the active provider. +- `nemoclaw status` reports the local vLLM or compatible endpoint as the + active provider. -If JSON still appears as text, confirm that you started vLLM with both `--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your model. +If JSON still appears as text, confirm that vLLM was started with both +`--enable-auto-tool-choice` and the correct `--tool-call-parser` value for your +model. ## Next Steps diff --git a/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md b/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md new file mode 100644 index 0000000000..fab5e58f2b --- /dev/null +++ b/skills/nemoclaw-user-configure-inference/references/use-local-inference-details.md @@ -0,0 +1,151 @@ + + +# Use a Local Inference Server: Details + +## Non-Interactive Setup + +```console +$ NEMOCLAW_PROVIDER=ollama \ + NEMOCLAW_MODEL=qwen2.5:14b \ + nemoclaw onboard --non-interactive --yes +``` + +If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. +If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. +Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. + +`--yes` (or `NEMOCLAW_YES=1`) authorises the Ollama model download without an interactive confirmation prompt. +Under `--non-interactive`, `--yes` (or `NEMOCLAW_YES=1`) is required to authorise the download — onboard exits otherwise, since it cannot prompt. +Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt that shows the model size before downloading. + +| Variable | Purpose | +|---|---| +| `NEMOCLAW_PROVIDER` | Set to `ollama`. | +| `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. | +| `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. | + +### Selecting the API Path + +For the compatible-endpoint provider, `/v1/chat/completions` is the default. +NemoClaw tests streaming events during onboarding and uses chat completions +without probing the Responses API. + +To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: + +```console +$ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard +``` + +The wizard then probes `/v1/responses` and only selects it when streaming +support is complete. +If the probe fails, the wizard falls back to `/v1/chat/completions` +automatically. +You can use this variable in both interactive and non-interactive mode. + +| Variable | Values | Default | +|---|---|---| +| `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | + +If you already onboarded and the sandbox is failing at runtime, re-run +`nemoclaw onboard` to re-probe the endpoint and bake the correct API path +into the image. +Refer to [Switch Inference Models](switch-inference-providers.md) for details. + +## Anthropic-Compatible Server + +If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. + +```console +$ nemoclaw onboard +``` + +For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. + +```console +$ NEMOCLAW_PROVIDER=anthropicCompatible \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ + NEMOCLAW_MODEL=my-model \ + COMPATIBLE_ANTHROPIC_API_KEY=dummy \ + nemoclaw onboard --non-interactive +``` + +### Override the Managed-vLLM Model + +Managed vLLM serves the profile default unless you select a different registry entry. +Export `NEMOCLAW_VLLM_MODEL=` before invoking the installer to choose a different model from the registry. +NemoClaw uses the matching `vllm serve` flags, including the reasoning parser, tool-call parser, and `--max-model-len`. +Recognised slugs: + +| Slug | Hugging Face model | Notes | +|---|---|---| +| `qwen3.6-27b` | `Qwen/Qwen3.6-27B-FP8` | Default on DGX Spark and DGX Station profiles | +| `nemotron-3-nano-4b` | `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8` | Default on the generic Linux + NVIDIA GPU profile | +| `deepseek-r1-distill-70b` | `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | Gated. Requires Hugging Face license acceptance | + +The slug is case-insensitive; the full Hugging Face id is also accepted. +An unrecognised value fails fast with a list of valid slugs. + +Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container: + +```console +$ export HF_TOKEN= +$ NEMOCLAW_PROVIDER=install-vllm \ + NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ + nemoclaw onboard --non-interactive +``` + +`HUGGING_FACE_HUB_TOKEN` is accepted 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. + +## Timeout Configuration + +Local inference requests use a default timeout of 180 seconds. +Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup. + +To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemoclaw onboard +``` + +The value is in seconds. +This setting is baked into the sandbox at build time. +Changing it after onboarding requires re-running `nemoclaw onboard`. + +`NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe. +The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds. +On hosts where the sandbox image takes minutes to build or upload — large quantised models, DGX Station first runs, or remote VMs over a slow link — raise both together: + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 +$ nemoclaw onboard +``` + +If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). + +## Verify the Configuration + +After onboarding completes, confirm the active provider and model. + +```console +$ nemoclaw status +``` + +The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. +For Local Ollama, status also checks the authenticated proxy when a proxy token is available. +If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use. + +## Switch Models at Runtime + +You can change the model without re-running onboard. +Refer to [Switch Inference Models](switch-inference-providers.md) for the full procedure. + +For compatible endpoints, the command is: + +```console +$ nemoclaw inference set --provider compatible-endpoint --model +``` + +If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. diff --git a/skills/nemoclaw-user-configure-security/SKILL.md b/skills/nemoclaw-user-configure-security/SKILL.md index 865e4aa6d8..36df08415f 100644 --- a/skills/nemoclaw-user-configure-security/SKILL.md +++ b/skills/nemoclaw-user-configure-security/SKILL.md @@ -4,10 +4,13 @@ description: "Presents a risk framework for every configurable security control license: "Apache-2.0" --- -# NemoClaw User Configure Security + + + +# NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles ## References - **Load [references/best-practices.md](references/best-practices.md)** when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs. Presents a risk framework for every configurable security control in NemoClaw. -- **Load [references/credential-storage.md](references/credential-storage.md)** when reviewing how credentials are handled, locating a stored credential, or assessing the storage threat model. Covers where NemoClaw stores provider credentials, why nothing is persisted to host disk, and how the OpenShell gateway acts as the single system of record. - **Load [references/openclaw-controls.md](references/openclaw-controls.md)** when reviewing the security boundary between NemoClaw and OpenClaw or assessing what NemoClaw does not cover. Lists OpenClaw security controls that operate independently of NemoClaw, including prompt injection detection, tool access control, rate limiting, environment variable policy, audit framework, supply chain scanning, messaging access policy, context visibility, and safe regex. +- **Load [references/credential-storage.md](references/credential-storage.md)** when reviewing how credentials are handled, locating a stored credential, or assessing the storage threat model. Covers where NemoClaw stores provider credentials, why nothing is persisted to host disk, and how the OpenShell gateway acts as the single system of record. diff --git a/skills/nemoclaw-user-configure-security/references/best-practices.md b/skills/nemoclaw-user-configure-security/references/best-practices.md index d3cfa873a7..59e3ceee9f 100644 --- a/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -1,24 +1,24 @@ + + # NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles -import { AgentOnly } from "../_components/AgentGuide"; - NemoClaw ships with deny-by-default security controls across four layers: network, filesystem, process, and inference. You can tune every control, but each change shifts the risk profile. -This page documents each configurable control, its default, what it protects, the concrete risk of relaxing it, and a recommendation for common use cases. +This page documents every configurable knob, its default, what it protects, the concrete risk of relaxing it, and a recommendation for common use cases. For background on how the layers fit together, refer to How It Works (use the `nemoclaw-user-overview` skill). ## Protection Layers at a Glance NemoClaw enforces security at four layers. -NemoClaw locks some controls when it creates the sandbox and requires a restart to change them. +NemoClaw locks some when it creates the sandbox and requires a restart to change them. You can hot-reload others while the sandbox runs. -The following diagram shows the default posture immediately after onboarding, before you approve any endpoints or apply any presets. +The following diagram shows the default posture immediately after `nemoclaw onboard`, before you approve any endpoints or apply any presets. ```mermaid flowchart TB - subgraph HOST["Your Machine: default posture after onboarding"] + subgraph HOST["Your Machine: default posture after nemoclaw onboard"] direction TB YOU["👤 Operator"] @@ -70,16 +70,15 @@ flowchart TB | Network | Unauthorized outbound connections and data exfiltration. | OpenShell gateway | Yes. Use `openshell policy set` or operator approval. | | Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Use host-side NemoClaw commands for durable config changes. | | Process | Privilege escalation, fork bombs, syscall abuse. | Container runtime (Docker/K8s `securityContext`) | No. Requires sandbox re-creation. | -| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use the NemoClaw inference switching command. | +| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use `nemoclaw inference set`. | ## Network Controls NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets operators approve or deny requests in real time. -Network policy allowlists do not disable OpenShell's SSRF guard; see Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for the interaction between egress rules and internal-address blocking. ### Deny-by-Default Egress -The sandbox blocks all outbound connections unless you explicitly list the endpoint in the applicable baseline policy files. +The sandbox blocks all outbound connections unless you explicitly list the endpoint in the policy file `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. | Aspect | Detail | |---|---| @@ -93,7 +92,7 @@ The sandbox blocks all outbound connections unless you explicitly list the endpo Each network policy entry restricts which executables can reach the endpoint using the `binaries` field. OpenShell identifies the calling binary by reading `/proc//exe` (the kernel-trusted executable path, not `argv[0]`), walking the process tree for ancestor binaries, and computing a SHA256 hash of each binary on first use. -If someone replaces a binary while the sandbox runs, the hash mismatch immediately denies the request. +If someone replaces a binary while the sandbox runs, the hash mismatch triggers an immediate deny. | Aspect | Detail | |---|---| @@ -127,12 +126,12 @@ The `protocol` field on an endpoint controls whether the proxy also inspects ind ### Operator Approval Flow -When the agent reaches an unlisted endpoint, OpenShell blocks the request and prompts you in the TUI. +When the agent reaches an unlisted endpoint, OpenShell blocks the request and prompts the operator in the TUI. | Aspect | Detail | |---|---| | Default | Enabled. The gateway blocks all unlisted endpoints and requires approval. | -| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox through onboarding, the policy resets to the baseline defined in the blueprint. | +| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox (for example, by running `nemoclaw onboard`), the policy resets to the baseline defined in the blueprint. | | Risk if relaxed | Approving an endpoint permanently widens the running sandbox's policy. If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. | | Recommendation | Review each blocked request before approving. If you find yourself approving the same endpoint repeatedly, add it to the baseline policy with appropriate binary and path restrictions. To reset approved endpoints, destroy and recreate the sandbox. | @@ -144,7 +143,6 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for |---|---|---| | `brave` | Brave Search API. | Agent can issue search queries. | | `brew` | Homebrew (Linuxbrew) package manager. The sandbox base image includes the `brew` binary; this preset opens network egress to GitHub and the Homebrew formulae index so `brew install` can fetch bottles. | Allows installing arbitrary Homebrew packages, which may contain malicious code. | -| `claude-code` | Claude Code CLI API, telemetry, and crash-report endpoints. | Allows a separately installed Claude Code CLI to reach Anthropic and telemetry hosts with its own credentials. Do not use this preset for NemoClaw inference routing. | | `discord` | Discord REST API, WebSocket gateway, CDN. | CDN endpoint (`cdn.discordapp.com`) allows GET to any path. WebSocket uses `access: full` (no inspection). | | `github` | GitHub and GitHub REST API. | Gives agent read/write access to repositories and issues via `git`. | | `huggingface` | Hugging Face Hub (download-only) and inference router. | Allows downloading arbitrary models and datasets. POST is restricted to the inference router only. | @@ -175,8 +173,6 @@ The container mounts system directories read-only to prevent the agent from modi ### Agent Config Directory - - The `/sandbox/.openclaw` directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config). The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as `OPENCLAW_GATEWAY_TOKEN`, and writes it to `/tmp/nemoclaw-proxy-env.sh` so interactive sandbox sessions can reach the gateway through system-wide shell hooks. In root mode, the gateway process still runs as the separate `gateway` user, but the token is intentionally available to sandbox shells for local gateway access. @@ -184,26 +180,10 @@ In root mode, the gateway process still runs as the separate `gateway` user, but Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under `/sandbox/.openclaw`. By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. -For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so the sandbox user cannot change config and high-risk state entry points. -The immutability workflow locks high-risk state directories (`skills`, `hooks`, `cron`, `agents`, `extensions`, `plugins`, `workspace`, `memory`, `devices`, `canvas`, `telegram`, `wechat`, `whatsapp`, `platforms`, `weixin`, `profiles`, `skins`) to `root:sandbox` with `chmod -R go-w`. -The OpenClaw gateway (a member of the `sandbox` group) keeps read access to plugin and agent code; the sandbox user can no longer write them. -The same workflow also locks the secret-bearing directories (`credentials`, `identity`, `pairing`) to `root:root 700` with `chmod -R go-rwX`. -Neither the sandbox user nor the gateway can read those secrets while the lock is active. -Restoring the mutable-default posture returns both groups to `sandbox:sandbox 2770`. -The list is the union of state directories declared by every shipped agent manifest; the lock helper silently skips dirs that aren't present in a given agent's config tree. -Two exemption kinds keep runtime data writable. -The lock inventory omits top-level Hermes runtime dirs (`sessions/`, `memories/`, `logs/`, `cache/`, `plans/`) and the image-build-regenerated `openclaw-weixin/`; the lock helper never touches those paths. -Inside a locked tree, the helper restores `agents//sessions/` to `sandbox:sandbox 2770` after the surrounding `agents/` lock so the OpenClaw TUI can create and write session metadata under an otherwise root-owned parent. -If any high-risk state-dir root is a symlink when the lock runs, the lock helper refuses to proceed and reports "Config not locked: state dir root is a symlink" instead of following the link with privileged `chown -R` / `chmod -R`. +For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so config and writable state entry points cannot be changed by the sandbox user. - **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `2770` (setgid `sandbox:sandbox`) and `openclaw.json` with mode `660`, so the agent and its group can read and write config directly. A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked. - **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match. -- **Content integrity seal.** - A clean immutable config lock can capture a SHA-256 seal of `openclaw.json` and other locked files into host-side state. - Verification recomputes hashes inside the sandbox and surfaces drift on mismatch, so a host-root tamper that flips permissions back to `444 root:root` after rewriting the file is still flagged. - Sandboxes locked before the seal landed have no recorded hash; permission-only verification cannot prove their bytes match the image original, so the seal is **not** a retroactive proof of integrity for legacy state. - The same limitation applies when the locked file set grew after the existing seal was captured. - Rebuild the sandbox for a known-good baseline before trusting a new seal. - **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture. | Aspect | Detail | @@ -213,25 +193,6 @@ If any high-risk state-dir root is a symlink when the lock runs, the lock helper | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | | Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | - - - -The `/sandbox/.hermes` directory contains Hermes runtime configuration, generated environment settings, logs, platform state, and durable database state. -NemoClaw writes `config.yaml` and `.env` during onboarding and rebuilds. -Direct edits to these files can be overwritten when NemoClaw regenerates the image. - -Hermes also stores runtime state such as `state.db`, logs, and platform sessions under the `.hermes` tree. -Messaging sessions such as WhatsApp pairing can remain mutable by design so they survive rebuilds. - -| Aspect | Detail | -|---|---| -| Default | The Hermes config tree contains NemoClaw-generated config plus mutable runtime state. | -| What you can change | Use host-side NemoClaw commands for durable model, provider, messaging, and policy changes; inspect files directly only for debugging. | -| Risk of direct edits | Direct edits to generated config can drift from the host registry and may be lost on rebuild. | -| Recommendation | For sensitive workloads, keep generated config under NemoClaw control and back up Hermes state before destructive operations. | - - - ### Writable Paths The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`. @@ -267,28 +228,20 @@ When the entrypoint switches from root to the `sandbox` and `gateway` users, it The initial entrypoint drop removes `cap_sys_admin`, `cap_sys_ptrace`, `cap_net_raw`, `cap_dac_override`, `cap_sys_chroot`, `cap_fsetid`, `cap_setfcap`, `cap_mknod`, `cap_audit_write`, and `cap_net_bind_service`. During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setgid`, `cap_fowner`, `cap_chown`, and `cap_kill`. -This behavior is best effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set. +This is best-effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set. If `setpriv` is unavailable, the entrypoint falls back to `gosu` and logs a warning that the remaining bounding-set capabilities were retained for the child process. - -To make the drop fail-closed instead of best-effort, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment. -The agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities, so it will not boot on a host whose bounding set still holds them — typically one that cannot perform the drop (no `CAP_SETPCAP`, or `capsh` missing) and was not given a clean bounding set by the container runtime. -This is opt-in because such hosts are common (many cloud VMs, Docker Desktop, WSL); leaving it unset preserves the best-effort default. -The check covers the agent process tree only — a `nemoclaw connect` shell is spawned by the container runtime outside that tree and is not affected (tracked in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452)). - - -For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose. Refer to Sandbox Hardening. - +For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose (see Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill)). | Aspect | Detail | |---|---| | Default | The entrypoint drops dangerous capabilities at startup using `capsh`, then uses `setpriv` during user step-down when possible. Best-effort. | -| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw onboarding flow, the entrypoint handles capability dropping automatically. | +| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw flow (with `nemoclaw onboard`), the entrypoint handles capability dropping automatically. | | Risk if relaxed | `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` expand kernel and process attack surface. `CAP_NET_RAW` allows raw socket access for network sniffing. `CAP_DAC_OVERRIDE` bypasses filesystem permission checks. If `capsh` or `setpriv` cannot run, the container retains more of the runtime-provided capability set. | | Recommendation | Run on an image that includes `capsh` and `setpriv` (the NemoClaw image includes them). For defense-in-depth, also pass `--cap-drop=ALL` at the container runtime level. | ### Gateway Process Isolation -The in-sandbox gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent. +The OpenClaw gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent. | Aspect | Detail | |---|---| @@ -312,7 +265,7 @@ The `no-new-privileges` flag prevents processes from gaining additional privileg A process limit caps the number of processes the sandbox user can spawn. The entrypoint sets both soft and hard limits using `ulimit -u 512`. -This behavior is best effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit. +This is best-effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit. | Aspect | Detail | |---|---| @@ -365,7 +318,7 @@ A registry compromise or accidental force-push cannot silently swap the sandbox | Default | `nemoclaw-blueprint/blueprint.yaml` pins the sandbox image by digest. A CI regression test blocks any mutable-tag reference from merging. | | What you can change | Contributors bumping the sandbox image must update the digest in `blueprint.yaml`. Release tooling should rewrite the digest automatically. | | Risk if relaxed | Reverting to a mutable tag (`:latest`) allows a registry-side change to replace the sandbox image without any blueprint update, which is a supply-chain risk. | -| Recommendation | Always reference the sandbox image by digest. If you build a custom image with the onboarding `--from` path, the digest constraint does not apply to your local build. | +| Recommendation | Always reference the sandbox image by digest. If you build a custom image with `nemoclaw onboard --from`, the digest constraint does not apply to your local build. | ### Auth Profile Permissions @@ -381,8 +334,6 @@ This prevents other users on the host from reading stored credentials. ## Gateway Authentication Controls - - The OpenClaw gateway authenticates devices that connect to the Control UI dashboard. NemoClaw hardens these defaults at image build time. @@ -425,21 +376,10 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Aspect | Detail | |---|---| -| Default | Startup auto-pairing and `connect`-time approval share one policy. NemoClaw approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat` or `cli`, and only for `operator.pairing`, `operator.read`, and `operator.write` scopes. All other clients or scopes are rejected and logged. | -| What you can change | This is not a user-facing knob. The allowlist is defined by NemoClaw's OpenClaw device-approval helper. | +| Default | The watcher approves devices with `clientId` set to `openclaw-control-ui` or `clientMode` set to `webchat`. All other clients are rejected and logged. | +| What you can change | This is not a user-facing knob. The allowlist is defined in the entrypoint script. | | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | -| Recommendation | No action needed. NemoClaw handles this automatically at startup and during `connect` for late scope upgrades. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | - - - - -Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. -Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. -NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. -Generated Hermes runtime files use OpenShell resolver placeholders for managed-tool and messaging credentials. -Hermes startup rejects raw secret-shaped values in sandbox-visible environment or config fields, while allowing empty values, migration sentinels, OpenShell resolver placeholders, and expected Slack placeholder forms. - - +| Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | ### CLI Secret Redaction @@ -450,31 +390,21 @@ The CLI automatically redacts secret patterns (API keys, bearer tokens, provider | Default | Enabled. The runner redacts secrets from stdout, stderr, and thrown error messages. | | What you can change | This is not a user-facing knob. The CLI enforces it on all command output paths. | | Risk if relaxed | Without redaction, secrets could appear in terminal scrollback, log files, or debug output shared in bug reports. | -| Recommendation | No action needed. If you share NemoClaw debug output, verify that no secrets appear in the collected diagnostics. | +| Recommendation | No action needed. If you share `nemoclaw debug` output, verify that no secrets appear in the collected diagnostics. | ### Memory Secret Scanner - - The NemoClaw plugin blocks the agent from writing likely secrets (API keys, tokens, private keys) into persistent memory files. The scanner intercepts Write, Edit, and similar tool calls targeting memory and workspace paths before they reach disk. | Aspect | Detail | |---|---| | Default | Enabled. The plugin registers a `before_tool_call` hook that scans for 14 high-confidence secret patterns. | -| What it covers | Three path classifiers, all enforced through `isMemoryPath()`, plus credential-shaped text such as provider API keys, OpenAI project keys with `sk-proj-` prefixes, and Slack app-level `xapp-` tokens. The path classifiers are: (1) absolute `MEMORY_PATH_SEGMENTS` such as `/.openclaw/memory/`, `/.openclaw/workspace/`, `/.openclaw/agents/`, `/.openclaw/skills/`, `/.openclaw/hooks/`, `/.openclaw/credentials/`, `/.openclaw/openclaw.json`, `/.nemoclaw/`; (2) canonical workspace basenames in `MEMORY_BASENAMES` (`IDENTITY.md`, `MEMORY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) matched regardless of the surrounding path; and (3) lexically-normalized workspace-relative writes matching `MEMORY_RELATIVE_PREFIXES` (`.openclaw/`, `.nemoclaw/`, `memory/`) or named workspace daily memory paths, for embedded-fallback mode where the host's path resolver is unavailable. | +| What it covers | Examples include `.openclaw/memory/`, `.openclaw/workspace/`, `.openclaw/agents/`, `.openclaw/skills/`, `.openclaw/hooks/`, `.openclaw/credentials/`, `.openclaw/openclaw.json`, `.nemoclaw/`, and `MEMORY.md`; the exact coverage is defined by `MEMORY_PATH_SEGMENTS` and enforced through `isMemoryPath()`. | | What you can change | This is not a user-facing knob. The plugin enforces it automatically. | | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | - - - -Hermes does not use the OpenClaw NemoClaw plugin memory scanner. -Keep secrets in environment variables or OpenShell providers, and avoid writing raw credentials to Hermes state files or workspace content. - - - ## Inference Controls OpenShell routes all inference traffic through the gateway to isolate provider credentials from the sandbox. @@ -489,7 +419,7 @@ The agent never receives the provider API key. | Default | The agent talks to `inference.local`. The host owns the credential and upstream endpoint. | | What you can change | You cannot configure this architecture. The system always enforces it. | | Risk if bypassed | If the agent could reach an inference endpoint directly (by adding it to the network policy), it would need an API key. Since the sandbox does not contain credentials, this acts as defense-in-depth. However, adding an inference provider's host to the network policy without going through OpenShell routing could let the agent use a stolen or hardcoded key. | -| Recommendation | Do not add inference provider hosts (such as `api.openai.com` or `api.anthropic.com`) to the network policy for NemoClaw model traffic. Use OpenShell inference routing instead. The `claude-code` preset is a separate opt-in exception for running the Claude Code CLI with its own credentials, not a way to configure NemoClaw inference. | +| Recommendation | Do not add inference provider hosts (such as `api.openai.com` or `api.anthropic.com`) to the network policy. Use OpenShell inference routing instead. | ### Provider Trust Tiers @@ -508,14 +438,12 @@ Different inference providers have different trust and cost profiles. ### Experimental Providers -The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and generic Linux managed vLLM install/start. -DGX Spark and DGX Station managed vLLM entries appear by default. -An already-running vLLM server on `localhost:8000` also appears in the menu without a flag because selecting it is an explicit user action. +The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and generic Linux managed vLLM install/start. DGX Spark and DGX Station managed vLLM entries are offered by default, and an already-running vLLM server on `localhost:8000` is offered in the menu without a flag, because selecting either is an explicit user action. | Aspect | Detail | |---|---| | Default | Local NVIDIA NIM and generic Linux managed vLLM install/start are hidden. DGX Spark and DGX Station managed vLLM entries, plus already-running vLLM on `localhost:8000`, are offered when detected. | -| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before onboarding to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. | +| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before running `nemoclaw onboard` to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. | | Risk if selected | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. The managed vLLM path pulls a container image and starts it on a supported NVIDIA GPU host. Misconfiguration can cause failed inference or unexpected behavior. | | Recommendation | Use experimental providers only for evaluation. Do not rely on them for always-on assistants. | @@ -561,16 +489,16 @@ The following patterns weaken security without providing meaningful benefit. | Omitting `protocol: rest` on REST API endpoints without a compatibility reason | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. Use L4 pass-through only for documented cases such as npm/Yarn on Node 22, where the client requires a CONNECT tunnel that L7 inspection would break. | | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. | | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. | -| Leaving generated agent config writable on sensitive workloads | The generated config tree contains model routing, channel settings, and runtime integration state (`/sandbox/.openclaw` for OpenClaw, `/sandbox/.hermes` for Hermes). Writable config lets the agent drift from host-managed policy and routing. | Keep generated config under NemoClaw control for always-on assistants handling sensitive data. | -| Adding inference provider hosts to the network policy for NemoClaw inference | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. Apply `claude-code` only when intentionally running the separate Claude Code CLI inside the sandbox. | +| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Lock config for always-on assistants handling sensitive data. | +| Adding inference provider hosts to the network policy | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. | | Disabling device auth for remote deployments | Without device auth, any device on the network can connect to the gateway without pairing. Combined with a cloudflared tunnel, this makes the dashboard publicly accessible and unauthenticated. | Keep `NEMOCLAW_DISABLE_DEVICE_AUTH` at its default (`0`). Only set it to `1` for local headless or development environments. | ## Known Limitations | Limitation | Impact | Mitigation | |-----------|--------|------------| -| Bypassing managed gateway paths | Network policy and inference auth are not enforced when an agent runtime is launched outside the NemoClaw-managed gateway path. | Use NemoClaw-managed sandbox entrypoints for production workflows. | -| Direct filesystem writes bypass application-layer scanners | Application-layer scanners can intercept agent tool calls, not arbitrary raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. Application-layer scanning is defense-in-depth, not a filesystem-level control. | +| `openclaw agent --local` bypasses gateway | Secret scanning, network policy, and inference auth are not enforced when the agent runs in local mode. | A runtime warning is emitted when `--local` is detected. Avoid `--local` for production workflows. A future OpenClaw-level hook will close this gap. | +| Direct filesystem writes bypass secret scanner | The scanner intercepts OpenClaw tool calls, not raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. The scanner is application-layer defense-in-depth, not a filesystem-level control. | | Base64/hex-encoded secrets are not detected | Content-based regex scanning cannot detect encoded or obfuscated secrets. | Use environment variables or credential stores instead of writing secrets to files. | ## Related Topics @@ -578,8 +506,6 @@ The following patterns weaken security without providing meaningful benefit. - Network Policies (use the `nemoclaw-user-reference` skill) for the full baseline policy reference. - Customize the Network Policy (use the `nemoclaw-user-manage-policy` skill) for static and dynamic policy changes. - Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill) for the operator approval flow. - -- Sandbox Hardening for container-level security measures. - +- Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill) for container-level security measures. - Inference Options (use the `nemoclaw-user-configure-inference` skill) for provider configuration details. - How It Works (use the `nemoclaw-user-overview` skill) for the protection layer architecture. diff --git a/skills/nemoclaw-user-configure-security/references/credential-storage.md b/skills/nemoclaw-user-configure-security/references/credential-storage.md index 26dc213e61..b40b676a20 100644 --- a/skills/nemoclaw-user-configure-security/references/credential-storage.md +++ b/skills/nemoclaw-user-configure-security/references/credential-storage.md @@ -1,40 +1,31 @@ + + # Credential Storage -import { AgentOnly } from "../_components/AgentGuide"; - NemoClaw does not persist provider credentials to host disk. The OpenShell gateway is the only system of record for stored credentials. -When you provide a provider credential, either interactively during `nemoclaw onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. +When you provide a provider credential — interactively during `nemoclaw onboard` or via an environment variable — NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret. - The sandbox-side OpenClaw gateway token is generated at container startup and is not rotated through provider credential commands. - - -Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. -Those files should contain resolver placeholders, not live provider credentials. -For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. -Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. - ## Where Credentials Live Provider credentials live in the OpenShell gateway store. List what is registered with: -```bash -openshell provider list +```console +$ openshell provider list ``` Or, equivalently, through NemoClaw: -```bash -nemoclaw credentials list +```console +$ nemoclaw credentials list ``` -Both commands show the provider names registered with the gateway. -The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. +Both surface the provider names that the gateway holds credentials for. The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. NemoClaw still keeps non-secret operational state under `~/.nemoclaw/` (such as the sandbox registry). That directory is created with mode `0700` and contains no credential material. @@ -48,16 +39,13 @@ This means you can: - 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 -When the host environment is empty, day-two operations such as `nemoclaw rebuild` and remote-provider updates can reuse the credential already registered with the OpenShell gateway. -Export the credential only when you want to create, replace, or rotate the stored provider value. - ## Deploy Reads from Environment Only `nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time. A typical deploy invocation looks like: -```bash -NVIDIA_API_KEY=nvapi-... \ +```console +$ NVIDIA_API_KEY=nvapi-... \ HF_TOKEN=hf_... \ TELEGRAM_BOT_TOKEN=... \ nemoclaw deploy my-instance @@ -73,8 +61,7 @@ When a private repo requires authentication NemoClaw runs `gh auth token`, which The GitHub CLI prefers an OS keychain when one is reachable: macOS Keychain on macOS, Windows Credential Manager on Windows, and Linux Secret Service (libsecret + a running D-Bus session) on Linux. On hosts where no keychain is reachable (CI runners, headless launches, WSL without a session bus, macOS contexts where Keychain access is blocked, etc.) `gh auth login` falls back to a `gh`-managed file under `~/.config/gh/` with mode `0600`. -NemoClaw treats both backends identically. -`gh auth token` returns the value, and NemoClaw stages it in `process.env` for the current run only. +NemoClaw treats both backends identically: `gh auth token` returns the value, and NemoClaw stages it in `process.env` for the current run only. If `gh` is not installed or not logged in, NemoClaw prompts for a personal access token for that single run; the prompted value is held in process memory and is not written to host disk. Run `gh auth login` if you want a persistent backing store (whichever one applies on your host) so future runs do not prompt. @@ -97,14 +84,14 @@ 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 +```console +$ NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard ``` To remove a credential from the gateway entirely: -```bash -nemoclaw credentials reset +```console +$ nemoclaw credentials reset ``` `` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure). diff --git a/skills/nemoclaw-user-configure-security/references/openclaw-controls.md b/skills/nemoclaw-user-configure-security/references/openclaw-controls.md index 13e31c8702..2ced0c76de 100644 --- a/skills/nemoclaw-user-configure-security/references/openclaw-controls.md +++ b/skills/nemoclaw-user-configure-security/references/openclaw-controls.md @@ -1,3 +1,5 @@ + + # OpenClaw Security Controls Beyond NemoClaw's Scope NemoClaw provides infrastructure-layer security through sandbox isolation, network policy, filesystem restrictions, SSRF validation, and credential handling. @@ -5,7 +7,7 @@ It delegates all application-layer security to OpenClaw. This page documents areas where NemoClaw adds no independent protection beyond what OpenClaw already provides. The details below reflect the OpenClaw documentation at the time of writing. -Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security) for the current state. +Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security/index) for the current state. ## Prompt Injection Detection and Prevention @@ -56,7 +58,7 @@ OpenClaw blocks environment variables that could enable code injection, privileg ## Security Audit Framework -OpenClaw runs more than 50 distinct automated security checks that cover configuration, credential handling, and sandbox posture. +OpenClaw runs automated security checks (50+ distinct check types) that cover configuration, credential handling, and sandbox posture. Run `openclaw security audit` to see all findings for your deployment. These checks include: @@ -92,7 +94,7 @@ OpenClaw controls who can interact with the agent through direct messages and gr | Control | Detail | |---|---| -| DM policy modes | Four modes: open, disabled, pairing, allowlist | +| DM policy modes | 4 modes: open, disabled, pairing, allowlist | | Group policies | Per-group access rules | | Per-sender authorization | Individual sender gating | | Command authorization | Command-level access control | @@ -110,7 +112,7 @@ OpenClaw restricts what supplemental context the agent can see and how it can mo ## Safe Regex (ReDoS Prevention) -OpenClaw includes safe regex compilation to prevent regular expression denial of service (ReDoS) attacks. +OpenClaw includes safe regex compilation to prevent Regular Expression Denial of Service (ReDoS) attacks. The implementation detects unsafe nested quantifiers, bounds input length, and caches results. ## Next Steps diff --git a/skills/nemoclaw-user-deploy-remote/SKILL.md b/skills/nemoclaw-user-deploy-remote/SKILL.md index 9885238e64..d2ac40e834 100644 --- a/skills/nemoclaw-user-deploy-remote/SKILL.md +++ b/skills/nemoclaw-user-deploy-remote/SKILL.md @@ -1,15 +1,18 @@ --- name: "nemoclaw-user-deploy-remote" -description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw dockerignore, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." +description: "Explains how to run NemoClaw on a remote GPU instance, including the deprecated Brev compatibility path and the preferred installer plus onboard flow. Use when deploying NemoClaw to a remote VM, onboarding a Brev instance, or migrating away from the legacy `nemoclaw deploy` wrapper. Trigger keywords - deploy nemoclaw remote gpu, nemoclaw brev cloud deployment, nemoclaw plugins, openclaw plugins, install openclaw plugin, nemoclaw onboard from dockerfile, nemoclaw brev web ui, nemoclaw getting started, brev quickstart, nvidia nemotron agent, nemoclaw sandbox hardening, container security, docker capabilities, process limits." license: "Apache-2.0" --- + + + # Deploy NemoClaw to a Remote GPU Instance ## Gotchas - The `nemoclaw deploy` command is deprecated. -- On Brev, set `CHAT_UI_URL` in the launchable environment configuration so the installer can read it when it builds the sandbox image. +- On Brev, set `CHAT_UI_URL` in the launchable environment configuration so it is available when the installer builds the sandbox image. ## Prerequisites @@ -21,6 +24,20 @@ 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`. +## Quick Start + +If your Brev instance is already up and has already been onboarded with a sandbox, start with the standard sandbox chat flow: + +```console +$ nemoclaw my-assistant connect +$ openclaw tui +``` + +This gets you into the sandbox shell first and opens the OpenClaw chat UI right away. +If the VM is fresh, run the standard installer on that host and then run `nemoclaw onboard` before trying `nemoclaw my-assistant connect`. + +If you are connecting from your local machine and still need to provision the remote VM, you can still use `nemoclaw deploy ` as the legacy compatibility path described below. + ## Deploy the Instance **Warning:** @@ -30,8 +47,8 @@ Prefer provisioning the remote host separately, then running the standard NemoCl Create a Brev instance and run the legacy compatibility flow: -```bash -nemoclaw deploy +```console +$ nemoclaw deploy ``` Replace `` with a name for your remote instance, for example `my-gpu-box`. @@ -44,7 +61,7 @@ The legacy compatibility flow performs the following steps on the VM: 1. Installs Docker and the NVIDIA Container Toolkit if a GPU is present. 2. Installs the OpenShell CLI. 3. Runs `nemoclaw onboard` (the setup wizard) to create the gateway, register providers, and launch the sandbox. -4. Starts optional host auxiliary services, such as the cloudflared tunnel, when `cloudflared` is available. Onboarding configures channel messaging, and the channels run through OpenShell-managed processes, not through `nemoclaw tunnel start`. +4. Starts optional host auxiliary services (for example the cloudflared tunnel) when `cloudflared` is available. Channel messaging is configured during onboarding and runs through OpenShell-managed processes, not through `nemoclaw tunnel start`. By default, the compatibility wrapper asks Brev to provision on `gcp`. Override this with `NEMOCLAW_BREV_PROVIDER` if you need a different Brev cloud provider. If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those values to the VM so remote setup can pull gated Hugging Face model repositories. @@ -54,43 +71,47 @@ If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox. To reconnect after closing the session, run the command again: -```bash -nemoclaw deploy +```console +$ nemoclaw deploy ``` ## Monitor the Remote Sandbox SSH to the instance and run the OpenShell TUI to monitor activity and approve network requests: -```bash -ssh 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term' +```console +$ ssh 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term' ``` ## Verify Inference Run a test agent prompt inside the remote sandbox: -```bash -openclaw agent --agent main -m "Hello from the remote sandbox" --session-id test +```console +$ 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: +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 accessing 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 will use **before** running setup: -```bash -export CHAT_UI_URL="https://openclaw0-.brevlab.com" -nemoclaw deploy +```console +$ export CHAT_UI_URL="https://openclaw0-.brevlab.com" +$ nemoclaw deploy ``` -For SSH port-forwarding, the origin is typically the default `http://127.0.0.1:18789`, so you do not need extra configuration. +For SSH port-forwarding, the origin is typically `http://127.0.0.1:18789` (the +default), so no extra configuration is needed. **Warning:** -On Brev, set `CHAT_UI_URL` in the launchable environment configuration so the installer can read it when it builds the sandbox image. -If you do not set `CHAT_UI_URL` on a headless host, the compatibility wrapper prints a warning. +On Brev, set `CHAT_UI_URL` in the launchable environment configuration so it is +available when the installer builds the sandbox image. If `CHAT_UI_URL` is not +set on a headless host, the compatibility wrapper prints a warning. `NEMOCLAW_DISABLE_DEVICE_AUTH` is also evaluated at image build time. When `CHAT_UI_URL` points at a non-loopback origin, NemoClaw disables OpenClaw device pairing in the generated sandbox configuration because browser-only remote users cannot complete terminal-based pairing. @@ -98,37 +119,37 @@ Any device that can reach the configured dashboard origin can connect without pa ## First-Run Readiness Budget -On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the host builds the sandbox image locally and uploads it into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts. -The post-create readiness wait defaults to 180 seconds (`NEMOCLAW_SANDBOX_READY_TIMEOUT`), which fits warm-cache, workstation-class onboarding but can be too short for: +On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the sandbox image is built locally and uploaded into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts. +The post-create readiness wait defaults to 180 seconds (`NEMOCLAW_SANDBOX_READY_TIMEOUT`), which is sized for warm-cache, workstation-class onboarding and can be exceeded on: -- DGX Station first runs with large quantized models (70B+ parameter footprints, NVFP4 weights). +- DGX Station first runs with large quantised models (70B+ parameter footprints, NVFP4 weights). - Cloud VMs where the local image-build cache is cold and the upload runs over the public network. - Hosts onboarding the Brave Web Search preset on the first run (the egress policy stack adds boot work). Raise the budget before re-running onboard: -```bash -export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 -nemoclaw onboard +```console +$ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 +$ nemoclaw onboard ``` -If onboard ends with `Sandbox '' was created but did not become ready within 180s`, onboard first deletes the partially created sandbox, so the next attempt with the raised budget starts from a clean state. -For the inference-probe budget that runs earlier in onboarding, refer to `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` (use the `nemoclaw-user-configure-inference` skill). +If onboard ends with `Sandbox '' was created but did not become ready within 180s`, onboard deletes the partially-created sandbox first, so the next attempt with the raised budget starts from a clean state. +For the inference-probe budget that runs earlier in onboarding, see `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` (use the `nemoclaw-user-configure-inference` skill). ## Proxy Configuration NemoClaw routes sandbox traffic through a gateway proxy that defaults to `10.200.0.1:3128`. If your network requires a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding: -```bash -export NEMOCLAW_PROXY_HOST=proxy.example.com -export NEMOCLAW_PROXY_PORT=8080 -nemoclaw onboard +```console +$ export NEMOCLAW_PROXY_HOST=proxy.example.com +$ export NEMOCLAW_PROXY_PORT=8080 +$ nemoclaw onboard ``` -NemoClaw bakes these values into the sandbox image at build time. -NemoClaw also forwards them into the runtime container during sandbox creation, so `/tmp/nemoclaw-proxy-env.sh` uses the same host and port that the image build used. -NemoClaw accepts only alphanumeric characters, dots, hyphens, and colons for the host. +These values are baked into the sandbox image at build time. +They are also forwarded into the runtime container during sandbox creation, so `/tmp/nemoclaw-proxy-env.sh` uses the same host and port that the image build used. +Only alphanumeric characters, dots, hyphens, and colons are accepted for the host. The port must be numeric (0-65535). Changing the proxy after onboarding requires re-running `nemoclaw onboard`. @@ -138,14 +159,14 @@ The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`. Set this variable before running `nemoclaw deploy` to use a different GPU configuration: -```bash -export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" -nemoclaw deploy +```console +$ export NEMOCLAW_GPU="a2-highgpu-1g:nvidia-tesla-a100:2" +$ nemoclaw deploy ``` ## References -- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox, including `.dockerignore` handling for custom build contexts. +- **Load [references/install-openclaw-plugins.md](references/install-openclaw-plugins.md)** when users ask how to install, build, or configure OpenClaw plugins under NemoClaw. Explains the difference between OpenClaw plugins and agent skills, and shows the current Dockerfile-based workflow for baking a plugin into a NemoClaw sandbox. - **Load [references/brev-web-ui.md](references/brev-web-ui.md)** when a user wants to try NemoClaw without installing the CLI, or asks how to get started on Brev. Guides users through deploying NemoClaw with the Brev web UI. - **Load [references/sandbox-hardening.md](references/sandbox-hardening.md)** when reviewing sandbox image security controls, auditing capability drops, or looking up the runtime resource limits. Includes the sandbox container image hardening reference, covering Docker capabilities and process limits. @@ -153,4 +174,4 @@ nemoclaw deploy - `nemoclaw-user-manage-sandboxes` — Set Up Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) to connect Telegram, Discord, or Slack through OpenShell-managed channel messaging - `nemoclaw-user-monitor-sandbox` — Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) for sandbox monitoring tools -- `nemoclaw-user-reference` — `nemoclaw deploy` (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference +- `nemoclaw-user-reference` — Commands (use the `nemoclaw-user-reference` skill) for the full `deploy` command reference diff --git a/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md b/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md index f0059b3c54..517e14b48d 100644 --- a/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md +++ b/skills/nemoclaw-user-deploy-remote/references/brev-web-ui.md @@ -1,3 +1,5 @@ + + # Launch NemoClaw with the Brev Web UI Use the Brev web UI to launch a hosted NemoClaw sandbox from your browser. @@ -27,8 +29,7 @@ You do not need to install local software for this flow. ## Get Your NVIDIA API Key -If you already have an NVIDIA API key, skip this section. -Otherwise, follow these steps to generate a new key: +If you already have an NVIDIA API key skip this section. Otherwise, follow these steps to generate a new key: 1. Go to [build.nvidia.com](https://build.nvidia.com). 2. Sign in or create an account. @@ -47,7 +48,7 @@ Use the [NemoClaw Brev launchable](https://brev.nvidia.com/launchable/deploy/now 2. Review the instance type, cloud provider, and estimated hourly cost on the NemoClaw setup page. 3. Click **Deploy NemoClaw**. -The deployment panel on the right shows progress while Brev deploys the CPU instance and prepares VM mode. +The right-side deployment panel shows progress while Brev deploys the CPU instance and prepares VM mode. Keep this page open until the deployment completes. When the panel shows the **NemoClaw** button, click it to open the agent setup page. @@ -97,8 +98,7 @@ Click **Chat With Agent** to open the OpenClaw dashboard. The dashboard might initially show a **Pairing required** warning. This means the gateway is still completing pairing in the background. -Wait a few minutes for pairing to finish automatically. -Refresh the dashboard to check whether the warning has cleared and the dashboard has connected. +Wait for about a few minutes for pairing to finish automatically. Refresh the dashboard to see if the warning is resolved and the connection is established. If pairing does not finish, go to the **Overview** page in the OpenClaw UI, find the **Gateway Access** panel, and click **Connect**. ## Start a Chat @@ -110,7 +110,7 @@ Hello! What can you do for me? What skills do you have available? ``` The agent reads its workspace files and introduces itself. -The starter workspace includes these example skills: +The starter workspace includes example skills such as: - **Weather** gets current weather and forecasts. - **Healthcheck** runs security audit and hardening checks. diff --git a/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md b/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md index 6f8e721920..b4b2f5beb8 100644 --- a/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md +++ b/skills/nemoclaw-user-deploy-remote/references/install-openclaw-plugins.md @@ -1,20 +1,22 @@ + + # Install OpenClaw Plugins -OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or provider integrations. -They are different from NemoClaw-managed agent skills: +OpenClaw plugins extend the OpenClaw runtime with hooks, services, tools, or +provider integrations. They are different from NemoClaw-managed agent skills: - **Plugins** are code packages loaded by OpenClaw. - **Skills** are `SKILL.md` directories that teach an agent how to perform a task. - **Policy presets** are network-egress rules that control what sandboxed code can reach. -The supported NemoClaw path for OpenClaw plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. +Today, the supported NemoClaw path for OpenClaw plugins is to bake the plugin +into a custom sandbox image and onboard from that Dockerfile. ## Prepare a Build Directory Put the Dockerfile and everything it needs to `COPY` in one directory. -`nemoclaw onboard --from ` uses the Dockerfile's parent directory as the Docker build context. -Add a `.dockerignore` next to the Dockerfile to exclude local caches, generated artifacts, model files, or other paths that are not needed by the image build. -NemoClaw still applies its own secret-safety exclusions for credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` negates them. +`nemoclaw onboard --from ` uses the Dockerfile's parent directory as +the Docker build context. ```text my-plugin-sandbox/ @@ -26,7 +28,8 @@ my-plugin-sandbox/ ## Example Dockerfile -Use the custom image to copy the plugin into the OpenClaw extensions directory and let OpenClaw refresh its config before NemoClaw starts the sandbox. +Use the custom image to copy the plugin into the OpenClaw extensions directory +and let OpenClaw refresh its config before NemoClaw starts the sandbox. ```dockerfile ARG SANDBOX_BASE=ghcr.io/nvidia/nemoclaw/sandbox-base:latest @@ -43,38 +46,48 @@ RUN mkdir -p /sandbox/.openclaw/extensions \ WORKDIR /opt/nemoclaw ``` -If the plugin needs configuration in `openclaw.json`, apply it after `openclaw doctor --fix` so the base config exists first. +If the plugin needs configuration in `openclaw.json`, apply it after +`openclaw doctor --fix` so the base config exists first. ## Create the Sandbox Point `nemoclaw onboard --from` at the Dockerfile in the build directory. -```bash -nemoclaw onboard --from ./my-plugin-sandbox/Dockerfile +```console +$ 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. +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. ## Network Access -Plugins still run inside the sandbox policy boundary. -If a plugin needs network egress, add or update a policy preset for the required hostnames and binaries before rebuilding the sandbox. +Plugins still run inside the sandbox policy boundary. If a plugin needs network +egress, add or update a policy preset for the required hostnames and binaries +before rebuilding the sandbox. -For policy concepts, refer to Network Policies (use the `nemoclaw-user-reference` skill). -For custom preset workflows, refer to Customize Network Policy (use the `nemoclaw-user-manage-policy` skill). +For example, see Network Policies (use the `nemoclaw-user-reference` skill) for +policy concepts and Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) +for custom preset workflows. ## Common Mistakes -These are the most common places where plugin installation gets mixed up with other NemoClaw extension paths. +These are the most common places where plugin installation gets mixed up with +other NemoClaw extension paths. -- Do not use `nemoclaw skill install` for OpenClaw plugins. That command only installs `SKILL.md` agent skills. -- Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend to send that whole directory as the Docker build context. -- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. +- Do not use `nemoclaw skill install` for OpenClaw plugins. That + command only installs `SKILL.md` agent skills. +- Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend + to send that whole directory as the Docker build context. - Keep plugin dependencies in the build stage or plugin directory; avoid copying unrelated host files into the sandbox image. ## Next Steps -- Review [Sandbox Hardening](sandbox-hardening.md) before adding plugin code to a shared or long-lived sandbox. -- Review Network Policies (use the `nemoclaw-user-reference` skill) to plan plugin egress rules. -- Follow Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) if the plugin needs a custom preset. +- Review [Sandbox Hardening](sandbox-hardening.md) before adding plugin code to a + shared or long-lived sandbox. +- Review Network Policies (use the `nemoclaw-user-reference` skill) to plan plugin + egress rules. +- Follow Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) + if the plugin needs a custom preset. diff --git a/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md b/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md index 11937ecd8f..669096f180 100644 --- a/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md +++ b/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md @@ -1,45 +1,50 @@ + + # Sandbox Image Hardening -The NemoClaw sandbox image applies several security measures to reduce attack surface and limit the blast radius of untrusted workloads. +The NemoClaw sandbox image applies several security measures to reduce attack +surface and limit the blast radius of untrusted workloads. ## Removed Unnecessary Tools -NemoClaw explicitly purges build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image. -These tools are not needed at runtime and would unnecessarily widen the attack surface. +Build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) are +explicitly purged from the runtime image. These tools are not needed at runtime +and would unnecessarily widen the attack surface. -The runtime image keeps a small set of operational utilities for normal sandbox workflows, including `vi`, `jq`, and `dos2unix`. -Use these utilities for lightweight inspection and file cleanup inside the sandbox, but make durable image or policy changes in the NemoClaw source tree and rebuild the sandbox. +The runtime image keeps a small set of operational utilities for normal sandbox +workflows, including `vi`, `jq`, and `dos2unix`. Use these for lightweight +inspection and file cleanup inside the sandbox, but make durable image or policy +changes in the NemoClaw source tree and rebuild the sandbox. -If you need a compiler during build, use the existing multi-stage build. -The `builder` stage has full Node.js tooling. -Copy only artifacts into the runtime stage. +If you need a compiler during build, use the existing multi-stage build +(the `builder` stage has full Node.js tooling) and copy only artifacts into the +runtime stage. ## Process Limits -The container ENTRYPOINT sets `ulimit -u 512` to cap the number of processes a sandbox user can spawn. -This mitigates fork-bomb attacks. -The startup script (`nemoclaw-start.sh`) applies the same limit. +The container ENTRYPOINT sets `ulimit -u 512` to cap the number of processes +a sandbox user can spawn. This mitigates fork-bomb attacks. The startup script +(`nemoclaw-start.sh`) applies the same limit. -Adjust the value with the `--ulimit nproc=512:512` flag if you launch with `docker run` directly. +Adjust the value via the `--ulimit nproc=512:512` flag if launching with +`docker run` directly. ## Dropping Linux Capabilities -The NemoClaw entrypoint drops dangerous capabilities from the process bounding set before it starts agent services. +The NemoClaw entrypoint drops dangerous capabilities from the process bounding +set before it starts agent services. It removes `CAP_SYS_ADMIN`, `CAP_SYS_PTRACE`, `CAP_NET_RAW`, `CAP_DAC_OVERRIDE`, `CAP_SYS_CHROOT`, `CAP_FSETID`, `CAP_SETFCAP`, `CAP_MKNOD`, `CAP_AUDIT_WRITE`, and `CAP_NET_BIND_SERVICE`. -When `setpriv` is available, the entrypoint also removes the remaining privilege-separation capabilities during the switch from root to the `sandbox` and `gateway` users. - -The bounding-set drop is best effort: if `capsh` or `CAP_SETPCAP` is unavailable the entrypoint logs a warning and continues with the runtime-provided capability set. -If `setpriv` is unavailable, the entrypoint falls back to `gosu`. -To make the drop fail-closed instead, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment: the agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities. -This is opt-in because hosts that cannot drop capabilities (no `CAP_SETPCAP` — many cloud VMs, Docker Desktop, WSL) are common, and the check covers the agent process tree only. +When `setpriv` is available, the entrypoint also removes the remaining +privilege-separation capabilities during the switch from root to the +`sandbox` and `gateway` users. For defense-in-depth, also drop all Linux capabilities at the container runtime when you launch the image directly: -```bash -docker run --rm \ +```console +$ docker run --rm \ --cap-drop=ALL \ --ulimit nproc=512:512 \ nemoclaw-sandbox @@ -78,15 +83,11 @@ The agent's home directory (`/sandbox`) is writable by default: | Path | Access | Purpose | |------|--------|---------| -| `/sandbox` | read-write | Home directory where agents can create files and use standard home paths | +| `/sandbox` | read-write | Home directory — agents can create files and use standard home paths | | `/sandbox/.openclaw` | read-write | Agent config, state, workspace, plugins | -| `/sandbox/.nemoclaw` | read-write (Landlock); DAC-restricted | Parent directory is `root:root` mode `1755`; the sandbox user can write only to `state/`, `migration/`, `snapshots/`, `staging/`, and `config.json`. `blueprints/` and the parent itself are root-owned to prevent tampering. | +| `/sandbox/.nemoclaw` | read-write | Plugin state and config; blueprints within are DAC-protected (root-owned) | | `/tmp` | read-write | Temporary files and logs | -The `Access` column reflects the Landlock policy declaration only. -Actual write success additionally requires POSIX (DAC) ownership and permissions to allow it. -For example, Landlock lists `/sandbox/.nemoclaw` as writable, but the sandbox user cannot create files directly under it because the parent directory is root-owned; writes must target the sandbox-owned subdirectories listed above. - This writable default is intentional. Seeing the sandbox user create files under `/sandbox` or `/sandbox/.openclaw` in a fresh sandbox does not mean Landlock failed. Landlock still enforces the fixed read-only system paths below. @@ -98,7 +99,7 @@ System paths remain read-only to prevent agents from: - Tampering with libraries or shell configuration outside `/sandbox` The image build pre-creates locked shell init files `.bashrc` and `.profile` without proxy entries. -System-wide shell hooks that read `/tmp/nemoclaw-proxy-env.sh` source the runtime proxy configuration. +Runtime proxy configuration is sourced from system-wide shell hooks that read `/tmp/nemoclaw-proxy-env.sh`. ### Landlock Kernel Requirements @@ -110,8 +111,8 @@ Files outside the writable paths would be inaccessible to the agent regardless o Operators should verify Landlock availability: -```bash -ls /sys/kernel/security/landlock +```console +$ ls /sys/kernel/security/landlock ``` For production deployments, kernel 5.13+ with Landlock enabled is strongly recommended. diff --git a/skills/nemoclaw-user-get-started/SKILL.md b/skills/nemoclaw-user-get-started/SKILL.md index 3056b491cd..97439a5b6f 100644 --- a/skills/nemoclaw-user-get-started/SKILL.md +++ b/skills/nemoclaw-user-get-started/SKILL.md @@ -3,22 +3,15 @@ name: "nemoclaw-user-get-started" description: "Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop." license: "Apache-2.0" --- - # NemoClaw Quickstart with OpenClaw Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent. **Note:** -Review the [Prerequisites](references/prerequisites.md) before following this guide. - -**Use Agent Skills:** +Make sure you have completed reviewing the [Prerequisites](references/prerequisites.md) before following this guide. -NemoClaw ships user skills for AI coding assistants. -Load them when you want your assistant to walk through installation, inference choices, policy approvals, monitoring, or troubleshooting with NemoClaw-specific guidance. -Refer to Agent Skills (use the `nemoclaw-user-agent-skills` skill). - -## Install NemoClaw and Onboard an OpenClaw Agent +## Install NemoClaw and Onboard OpenClaw Agent Download and run the installer script. The script installs Node.js if it is not already present, then runs the guided onboard wizard to create a sandbox, configure inference, and apply security policies. @@ -31,51 +24,34 @@ NemoClaw creates a fresh OpenClaw instance inside the sandbox during the onboard curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -The third-party software notice runs before the installer installs Node.js or the NemoClaw CLI. -The piped installer can prompt through your terminal when a TTY is available. -In non-TTY contexts, such as CI, an SSH command with piped stdin, or a shell script, pass explicit acceptance to the `bash` side of the pipe: - -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash -``` - -Or pass the installer flag through `bash -s`: +The piped installer prompts through your terminal. In headless scripts or CI, +pass explicit acceptance to the `bash` side of the pipe: -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software +```console +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash ``` -To run both installation and onboarding without prompts, also set non-interactive mode and the provider variables your chosen inference path requires: - -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash -``` - -Do not place `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1` before `curl`. -In `NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 curl ... | bash`, the variable applies only to `curl`, so the installer process cannot see the acceptance. - If you use nvm or fnm to manage Node.js, the installer might not update your current shell's PATH. If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal. On Linux, the installer checks Docker before it installs NemoClaw. If Docker is missing, the installer downloads the official Docker convenience script, asks for `sudo`, installs Docker, and starts the Docker service when systemd is available. -If you installed Docker but your current shell cannot use the Docker socket yet, the installer adds your user to the `docker` group when needed and exits with a recovery command. +If Docker is installed but your current shell cannot use the Docker socket yet, the installer adds your user to the `docker` group when needed and exits with a recovery command. On macOS, the installer uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima. -```bash -newgrp docker -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```console +$ newgrp docker +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. -On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, and local-inference presets. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. -The installer auto-launches `nemoclaw onboard` when it can locate the freshly installed binary. +The installer auto-launches `nemoclaw onboard` when it can locate the freshly-installed binary. If it cannot locate the binary, or if blocking host preflight checks fail, it does not launch the wizard automatically. In that case, the installer prints the relevant diagnostics and a `To finish setup, run:` block with the explicit `nemoclaw onboard` command. @@ -85,59 +61,6 @@ The onboard flow builds the sandbox image with `NEMOCLAW_DISABLE_DEVICE_AUTH=1` This is a build-time setting baked into the sandbox image, not a runtime knob. If you export `NEMOCLAW_DISABLE_DEVICE_AUTH` after onboarding finishes, it has no effect on an existing sandbox. -### Respond to the Onboard Wizard - -After the installer launches `nemoclaw onboard`, the wizard runs preflight checks, starts or reuses the OpenShell gateway, asks for an inference provider and model, collects any required credential, then asks for the sandbox name. -It prints a review summary before it registers the provider with OpenShell. -After you confirm, NemoClaw registers inference, prompts for optional web search and messaging channels, builds and starts the sandbox, sets up OpenClaw, then applies the selected network policy tier and presets. -At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. -If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches. - -The inference provider prompt presents a numbered list. - -```text - 1) NVIDIA Endpoints - 2) OpenAI - 3) Other OpenAI-compatible endpoint - 4) Anthropic - 5) Other Anthropic-compatible endpoint - 6) Google Gemini - 7) Local Ollama (localhost:11434) - 8) Model Router (experimental) - Choose [1]: -``` - -Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. -For the full list of providers and validation behavior, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). -Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. -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`. -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 - -Pick the option that matches where you want inference traffic to go. -For full provider behavior, curated models, validation details, and local-runtime setup notes, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). -For Ollama, vLLM, NIM, and compatible local servers, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). - -| Option | Use when | Credential variable | -|---|---|---| -| NVIDIA Endpoints | You want hosted models from `build.nvidia.com`, including hosted Nemotron models. | `NVIDIA_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` | - -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. - ### Review the Configuration Before the Sandbox Build After you enter the sandbox name, the wizard prints a review summary and asks for final confirmation before registering the provider, prompting for optional integrations, and building the sandbox image. @@ -149,9 +72,8 @@ For example, if you picked an OpenAI-compatible endpoint, the summary looks like ────────────────────────────────────────────────── Provider: compatible-endpoint Model: openai/openai/gpt-5.5 - API key: configured for OpenShell gateway registration + API key: COMPATIBLE_API_KEY (staged for OpenShell gateway registration) Web search: disabled - Managed tools: none Messaging: none Sandbox name: my-gpt-claw Note: Sandbox build typically takes 5–15 minutes on this host. @@ -160,7 +82,7 @@ For example, if you picked an OpenAI-compatible endpoint, the summary looks like Apply this configuration? [Y/n]: ``` -The default is `Y`, so you can press Enter one time to continue. Answer `n` to abort cleanly, fix the entries, and re-run `nemoclaw onboard`. +The default is `Y`, so you can press Enter once to continue. Answer `n` to abort cleanly, fix the entries, and re-run `nemoclaw onboard`. Non-interactive runs (`NEMOCLAW_NON_INTERACTIVE=1`) print the summary for log clarity but skip the prompt. @@ -172,7 +94,6 @@ If you enable it, enter a Brave Search API key when prompted. The wizard also offers messaging channels such as Telegram, Discord, Slack, WeChat, and WhatsApp. Press a channel number to toggle it, then press Enter to continue. -If you leave all channels unselected, pressing Enter skips messaging setup. If you select a channel, NemoClaw validates the token format before it bakes the channel configuration into the sandbox. For example, Slack bot tokens must start with `xoxb-`. WeChat and WhatsApp are experimental. @@ -181,8 +102,7 @@ Review Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill) befor ### Choose Network Policy Presets After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. -Web search and messaging selections happen before this point so the sandbox image and the policy suggestions stay aligned. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, read-only weather lookups, and Brave Search when the selected agent supports web search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. @@ -190,7 +110,7 @@ Press `r` to toggle a selected preset between read-only and read-write when the When the install completes, a summary confirms the running environment. Before printing the summary, NemoClaw verifies that the sandbox gateway and dashboard port forward are reachable. -NemoClaw reports inference route and messaging bridge checks as warnings when they need more time or additional configuration. +Inference route and messaging bridge checks are reported as warnings when they need more time or additional configuration. The `Model` and provider line reflects the inference option you picked during onboarding. The example below shows the result if you picked an OpenAI-compatible endpoint during onboarding. @@ -227,6 +147,8 @@ Manage later If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, `nvidia-routed (Model Router)`, or ` (Other OpenAI-compatible endpoint)`. +Load [references/quickstart-details.md](references/quickstart-details.md) for detailed steps on Respond to the Onboard Wizard. + ## Run Your First Agent Prompt You can chat with the agent from the terminal or the browser. @@ -236,7 +158,7 @@ You can chat with the agent from the terminal or the browser. The onboard wizard starts a background port forward to the sandbox dashboard, then prints the dashboard URL in the install summary. The default host port is `18789`. If that port is already taken, NemoClaw uses the next free dashboard port, such as `18790`, and prints that port in the final URL. -If the chosen port becomes occupied after the sandbox build starts, onboarding rolls back the newly created sandbox and asks you to retry instead of printing an unreachable dashboard URL. +If the chosen port becomes occupied after the sandbox build starts, onboarding rolls back the newly-created sandbox and asks you to retry instead of printing an unreachable dashboard URL. The install transcript does not print the gateway token. If the browser requires authentication, use the `dashboard-url --quiet` command to print a complete URL explicitly. @@ -260,11 +182,11 @@ openclaw tui ## References -- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes dashboard and API endpoint. +- **Load [references/quickstart-hermes.md](references/quickstart-hermes.md)** when users ask for Hermes setup, NemoHermes onboarding, or running Hermes inside OpenShell. Installs NemoClaw, selects the Hermes agent, and launches a sandboxed Hermes API endpoint. - **Load [references/prerequisites.md](references/prerequisites.md)** when verifying prerequisites before installation. Lists the hardware, software, and container runtime requirements for running NemoClaw. - **Load [references/windows-preparation.md](references/windows-preparation.md)** when preparing a Windows machine for NemoClaw, enabling WSL 2, configuring Docker Desktop for Windows, or troubleshooting a Windows-specific install error. Covers Windows-only preparation steps required before the Quickstart. +- **Load [references/quickstart-details.md](references/quickstart-details.md)** when you need detailed steps for Respond to the Onboard Wizard. ## Related Skills - `nemoclaw-user-overview` — NemoClaw Overview (use the `nemoclaw-user-overview` skill) to learn what NemoClaw is and its capabilities -- `nemoclaw-user-agent-skills` — Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant diff --git a/skills/nemoclaw-user-get-started/references/prerequisites.md b/skills/nemoclaw-user-get-started/references/prerequisites.md index 4e7b25437f..776cba7577 100644 --- a/skills/nemoclaw-user-get-started/references/prerequisites.md +++ b/skills/nemoclaw-user-get-started/references/prerequisites.md @@ -1,6 +1,6 @@ # Prerequisites -Before you start, verify that your machine has the software and hardware needed to run NemoClaw. +Before getting started, check the prerequisites to ensure you have the necessary software and hardware to run NemoClaw. ## Hardware @@ -10,11 +10,7 @@ Before you start, verify that your machine has the software and hardware needed | RAM | 8 GB | 16 GB | | Disk | 20 GB free | 40 GB free | -The sandbox image is approximately 2.4 GB compressed. -During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline. -The pipeline buffers decompressed layers in memory. -On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. -If you cannot add memory, configure at least 8 GB of swap to work around the issue at the cost of slower performance. +The sandbox image is approximately 2.4 GB compressed. During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline. The pipeline buffers decompressed layers in memory. On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. If you cannot add memory, configuring at least 8 GB of swap can work around the issue at the cost of slower performance. ## Software @@ -28,9 +24,8 @@ If you cannot add memory, configure at least 8 GB of swap to work around the iss On Linux, the installer can install Docker, start the Docker service, and add your user to the `docker` group. If the group change is not active in the current shell, the installer exits with `newgrp docker` guidance before it starts onboarding. If you choose the native Linux Ollama install path, the onboard wizard also requires `zstd` for Ollama archive extraction. -The installer also requires `strings` from `binutils` to verify the OpenShell binary before it continues with OpenShell install work. -**Docker Group Access:** +**Docker group access:** NemoClaw needs Docker access. On personal Linux development machines, adding your user to the `docker` group is the standard way to run Docker without sudo. @@ -38,11 +33,6 @@ Members of the `docker` group can control the daemon with root-level impact, so For background, review Docker's [daemon attack surface guidance](https://docs.docker.com/engine/security/#docker-daemon-attack-surface). On Debian and Ubuntu, NemoClaw installs `zstd` with `apt-get` if it is missing; on other Linux distributions, install `zstd` before onboarding. -If the installer reports that `strings` is missing, install `binutils` and rerun the installer: - -```bash -sudo apt-get install -y binutils -``` On macOS, NemoClaw uses the Docker-driver OpenShell gateway path with Docker Desktop or Colima. You do not need to install or sign a separate OpenShell VM driver helper for standard macOS onboarding. @@ -52,17 +42,17 @@ You do not need to install or sign a separate OpenShell VM driver helper for sta 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`. -**Docker Storage Driver:** +**Docker storage driver:** On Linux hosts running Docker 26 or later with the [containerd image store](https://docs.docker.com/engine/storage/containerd/) enabled (the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros), `nemoclaw onboard` transparently builds a `fuse-overlayfs`-enabled cluster image to bypass a kernel-level nested-overlay limitation in k3s. -You do not need manual setup. -Refer to the troubleshooting guide (use the `nemoclaw-user-reference` skill) for the override knobs and a manual `daemon.json` alternative. +No manual setup is required. +See the troubleshooting guide (use the `nemoclaw-user-reference` skill) for the override knobs and a manual `daemon.json` alternative. ## Platforms The following table lists tested platform and runtime combinations. Availability is not limited to these entries, but untested configurations can have issues. -The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. +The table is generated from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. | OS | Container runtime | Status | Notes | |----|-------------------|--------|-------| @@ -73,6 +63,5 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC ## Next Steps -- Prepare Windows for NemoClaw if you are using Windows. -- [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandboxed agent. -- Agent Skills (use the `nemoclaw-user-agent-skills` skill) to load NemoClaw guidance into an AI coding assistant before setup. +- [Prepare Windows for NemoClaw](windows-preparation.md) if you are using Windows. +- [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandbox. diff --git a/skills/nemoclaw-user-get-started/references/quickstart-details.md b/skills/nemoclaw-user-get-started/references/quickstart-details.md new file mode 100644 index 0000000000..1caf356ffb --- /dev/null +++ b/skills/nemoclaw-user-get-started/references/quickstart-details.md @@ -0,0 +1,165 @@ +# NemoClaw Quickstart with OpenClaw: Details + +## Respond to the Onboard Wizard + +After the installer launches `nemoclaw onboard`, the wizard runs preflight checks, starts or reuses the OpenShell gateway, and asks for an inference provider, sandbox name, optional web search, optional messaging channels, and network policy presets. +At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. +If existing sandbox sessions are running, the installer warns before onboarding because the setup can rebuild or upgrade sandboxes after the new sandbox launches. + +The inference provider prompt presents a numbered list. + +```text + 1) NVIDIA Endpoints + 2) OpenAI + 3) Other OpenAI-compatible endpoint + 4) Anthropic + 5) Other Anthropic-compatible endpoint + 6) Google Gemini + 7) Local Ollama (localhost:11434) + 8) Model Router (experimental) + Choose [1]: +``` + +Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. +For the full list of providers and validation behavior, refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). +Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. +The Model Router option appears when the blueprint router profile is enabled. + +**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`. +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. + +**Option 1: NVIDIA Endpoints:** + +Routes inference to models hosted on [build.nvidia.com](https://build.nvidia.com). + +Use `NVIDIA_API_KEY` for the API key. Get one from the [NVIDIA build API keys page](https://build.nvidia.com/settings/api-keys). + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, press Enter (or type `1`) to select **NVIDIA Endpoints**. +2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. +3. At the `Choose model [1]:` prompt, pick a curated model from the list (for example, `Nemotron 3 Super 120B`, `GLM-5`, `MiniMax M2.7`, `GPT-OSS 120B`, or `DeepSeek V4 Pro`), or pick `Other...` to enter any model ID from the [NVIDIA Endpoints catalog](https://build.nvidia.com). + +NemoClaw validates the model against the catalog API before creating the sandbox. + +**Tip:** + +Use this option for Nemotron and other models hosted on `build.nvidia.com`. If you run NVIDIA Nemotron from a self-hosted NIM, an enterprise gateway, or any other endpoint, choose **Option 3** instead, since all Nemotron models expose OpenAI-compatible APIs. + +**Option 2: OpenAI:** + +Routes inference to the OpenAI API at `https://api.openai.com/v1`. + +Use `OPENAI_API_KEY` for the API key. Get one from the [OpenAI API keys page](https://platform.openai.com/api-keys). + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `2` to select **OpenAI**. +2. At the `OPENAI_API_KEY:` prompt, paste your key if it is not already exported. +3. At the `Choose model [1]:` prompt, pick a curated model (for example, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, or `gpt-5.4-pro-2026-03-05`), or pick **Other...** to enter any OpenAI model ID. + +**Option 3: Other OpenAI-Compatible Endpoint:** + +Routes inference to any server that implements `/v1/chat/completions`, including OpenRouter, LocalAI, llama.cpp, vLLM behind a proxy, and any compatible gateway. + +Use `COMPATIBLE_API_KEY` for the API key. Set it to whatever credential your endpoint expects. If your endpoint does not require auth, use any non-empty placeholder. + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `3` to select **Other OpenAI-compatible endpoint**. +2. At the `OpenAI-compatible base URL` prompt, enter the provider's base URL. Find the exact value in your provider's API documentation. NemoClaw appends `/v1` automatically, so leave that suffix off. +3. At the `COMPATIBLE_API_KEY:` prompt, paste your key if it is not already exported. +4. At the `Other OpenAI-compatible endpoint model []:` prompt, enter the model ID exactly as it appears in your provider's model catalog. + +For example, when you use NVIDIA's OpenAI-compatible inference endpoint, enter `https://inference-api.nvidia.com` as the base URL and the model ID your endpoint exposes, such as `openai/openai/gpt-5.5`. + +NemoClaw sends a real inference request to validate the endpoint and model. +If the endpoint does not return the streaming events OpenClaw needs from the Responses API, NemoClaw falls back to the chat completions API and configures OpenClaw to use `openai-completions`. + +**Tip:** + +NVIDIA Nemotron models expose OpenAI-compatible APIs, so this option is the right choice for any Nemotron deployment that does not live on `build.nvidia.com`. Common examples include a self-hosted NIM container, an enterprise NVIDIA AI Enterprise gateway, or a vLLM/SGLang server running Nemotron weights. Point the base URL at your endpoint and enter the Nemotron model ID exactly as your server reports it. + +**Option 4: Anthropic:** + +Routes inference to the Anthropic Messages API at `https://api.anthropic.com`. + +Use `ANTHROPIC_API_KEY` for the API key. Get one from the [Anthropic console keys page](https://console.anthropic.com/settings/keys). + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `4` to select **Anthropic**. +2. At the `ANTHROPIC_API_KEY:` prompt, paste your key if it is not already exported. +3. At the `Choose model [1]:` prompt, pick a curated model (for example, `claude-sonnet-4-6`, `claude-haiku-4-5`, or `claude-opus-4-6`), or pick **Other...** to enter any Claude model ID. + +**Option 5: Other Anthropic-Compatible Endpoint:** + +Routes inference to any server that implements the Anthropic Messages API at `/v1/messages`, including Claude proxies, Bedrock-compatible gateways, and self-hosted Anthropic-compatible servers. + +Use `COMPATIBLE_ANTHROPIC_API_KEY` for the API key. Set it to whatever credential your endpoint expects. + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `5` to select **Other Anthropic-compatible endpoint**. +2. At the `Anthropic-compatible base URL` prompt, enter the proxy or gateway's base URL from its documentation. +3. At the `COMPATIBLE_ANTHROPIC_API_KEY:` prompt, paste your key if it is not already exported. +4. At the `Other Anthropic-compatible endpoint model []:` prompt, enter the model ID exactly as it appears in your gateway's model catalog. + +**Option 6: Google Gemini:** + +Routes inference to Google's OpenAI-compatible Gemini endpoint at `https://generativelanguage.googleapis.com/v1beta/openai/`. + +Use `GEMINI_API_KEY` for the API key. Get one from [Google AI Studio API keys](https://aistudio.google.com/app/apikey). + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `6` to select **Google Gemini**. +2. At the `GEMINI_API_KEY:` prompt, paste your key if it is not already exported. +3. At the `Choose model [5]:` prompt, pick a curated model (for example, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, or `gemini-2.5-flash-lite`), or pick **Other...** to enter any Gemini model ID. + +**Option 7: Local Ollama:** + +Routes inference to a local Ollama instance. Depending on your platform, the wizard can use an existing daemon, start an installed daemon, or offer an install action. + +No API key is required. On non-WSL hosts, NemoClaw generates a token and starts an authenticated proxy so containers can reach Ollama without exposing the daemon directly to your network. +On WSL, NemoClaw can also use Ollama on the Windows host through `host.docker.internal`. + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `7` to select **Local Ollama**. +2. At the `Choose model [1]:` prompt, pick from **Ollama models** if any are already installed. If none are installed, pick a **starter model** to pull and load now, or pick **Other...** to enter any Ollama model ID. + +For setup details, including GPU recommendations and starter model choices, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). + +**Option 8: Model Router:** + +Starts a host-side model router and routes sandbox inference through OpenShell to that router. +The router chooses from the model pool in `nemoclaw-blueprint/router/pool-config.yaml` for each request. + +Use `NVIDIA_API_KEY` for the model pool credentials. + +Respond to the wizard as follows. + +1. At the `Choose [1]:` prompt, type `8` to select **Model Router (experimental)**. +2. At the `NVIDIA_API_KEY:` prompt, paste your key if it is not already exported. +3. Review the configuration summary and continue with the sandbox build. + +For scripted setup, set: + +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive +``` + +The router listens on the host at port `4000`. +The sandbox still calls `https://inference.local/v1`, so do not point in-sandbox tools at the host router port directly. + +**Local NIM and Local vLLM:** + +- **Local NVIDIA NIM** appears when `NEMOCLAW_EXPERIMENTAL=1` is set and the host has a NIM-capable GPU. NemoClaw pulls and manages a NIM container. +- **Local vLLM (already running)** appears whenever NemoClaw detects a vLLM server on `localhost:8000`. No flag is required for the menu entry. NemoClaw auto-detects the loaded model. +- **Local vLLM (managed install/start)** appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls and starts a vLLM container on supported hosts. + +For setup, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). diff --git a/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index b475cdf1eb..dccb32a93c 100644 --- a/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -3,11 +3,12 @@ Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent. The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected. +**Experimental Feature:** + +The Hermes agent option is experimental. +Interfaces, defaults, and supported features may change without notice, and it is not recommended for production use. + Review the [Prerequisites](prerequisites.md) before starting. -Install Docker, start it, and verify that the current shell can reach it before Hermes onboarding builds the sandbox image. -On Linux, the installer can install Docker, start the service, and add your user to the `docker` group. -If it changes group membership, run the printed `newgrp docker` recovery command before rerunning the installer. -On macOS, start Docker Desktop or Colima before you run the installer. The first Hermes build can take several minutes because NemoClaw builds the Hermes sandbox base image if it is not already cached. ## Install and Onboard @@ -15,36 +16,20 @@ The first Hermes build can take several minutes because NemoClaw builds the Herm Start the installer with `NEMOCLAW_AGENT=hermes` set in your shell. The installer installs the CLI, selects the `nemohermes` alias, and runs the guided onboarding flow. -```bash -export NEMOCLAW_AGENT=hermes -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -``` - -If a headless host needs to expose the Hermes dashboard through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. -Use the externally reachable origin for the dashboard port `18789`. -NemoClaw derives the forwarded dashboard port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final dashboard URL in the ready summary. -The OpenAI-compatible API remains available separately on port `8642`. - -```bash -export NEMOCLAW_AGENT=hermes -export CHAT_UI_URL="https://hermes.example.com:18789" -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```console +$ export NEMOCLAW_AGENT=hermes +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -For SSH local port forwarding to `127.0.0.1:18789`, leave `CHAT_UI_URL` unset. -Do not append an OpenClaw `#token=` fragment to the Hermes dashboard URL. -Hermes API clients authenticate with the bearer token from the generated Hermes environment instead of an OpenClaw dashboard URL token. - If NemoClaw is already installed, start Hermes onboarding directly. -```bash -nemohermes onboard +```console +$ nemohermes onboard ``` ## Respond to the Wizard -The onboard wizard asks for an inference provider, model, any required credential, and sandbox name before it prints the review summary. -After you confirm, NemoClaw registers inference, prompts for supported messaging channels, builds and starts the sandbox, sets up Hermes, then applies the selected network policy tier and presets. +The onboard wizard asks for a sandbox name, inference provider, model, credentials, and network policy preset. At any prompt, press Enter to accept the default shown in `[brackets]`, type `back` to return to the previous prompt, or type `exit` to quit. The default Hermes sandbox name is `hermes`. @@ -57,13 +42,10 @@ Sandbox name [hermes]: my-hermes Choose the inference provider that matches where you want Hermes model traffic to go. The provider options and credential environment variables are the same as the standard NemoClaw quickstart. -For provider-specific prompts, refer to the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. +For provider-specific prompts, refer to the [Respond to the Onboard Wizard](../SKILL.md#respond-to-the-onboard-wizard) section and the Inference Options (use the `nemoclaw-user-configure-inference` skill) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. -If you authenticate Hermes through Nous Portal OAuth, the wizard can also prompt for managed Nous tool gateways such as web search, image generation, audio, browser automation, or managed code execution. -Those choices add the matching Hermes policy presets to the sandbox. -API-key mode is inference-only and does not enable managed tool gateways. -After provider and model selection, review the summary and confirm the build. +After provider and policy selection, review the summary and confirm the build. NemoClaw writes Hermes configuration into `/sandbox/.hermes`, routes model traffic through `inference.local`, and starts the Hermes gateway inside the sandbox. The Hermes image includes runtime dependencies for the supported NemoClaw messaging integrations, API service, and health endpoint. The base image does not include unsupported Hermes integrations. @@ -77,26 +59,21 @@ Hermes uses an agent-specific baseline policy that allows the Hermes binary and For CI or scripted installs, set the required environment variables before running the installer. The example below uses NVIDIA Endpoints and creates a sandbox named `my-hermes`. -```bash -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= -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +```console +$ 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= +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` Use the provider variables from Inference Options (use the `nemoclaw-user-configure-inference` skill) when you choose a different provider. ## Connect to Hermes -When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes dashboard 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 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. -Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` before onboarding only if you want Hermes' optional in-browser TUI tab. +When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, and Hermes API endpoint. +Hermes exposes an OpenAI-compatible API on port `8642`, not a browser dashboard. ```text ────────────────────────────────────────────────── @@ -107,9 +84,9 @@ Model: nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) Access - Hermes Agent Dashboard - 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 @@ -128,74 +105,59 @@ To chat with the agent from a terminal, follow these steps: 1. Connect to the sandbox and start the Hermes CLI. - ```bash - nemohermes my-hermes connect + ```console + $ nemohermes my-hermes connect ``` 2. Inside the sandbox, run the Hermes CLI. - ```bash - hermes + ```console + $ hermes ``` -## Open the Dashboard - -The onboard flow starts the dashboard port forward automatically. -Open the dashboard from the host: - -```console -$ nemohermes my-hermes dashboard-url --quiet -http://127.0.0.1:18789/ -``` - -Hermes handles dashboard sessions itself, so this URL does not include an OpenClaw `#token=` fragment. - ## Check the API Endpoint -The onboard flow also starts the API port forward automatically. +The onboard flow starts the port forward automatically. Check the health endpoint from the host to confirm that the Hermes API is reachable. -```bash -curl -sf http://127.0.0.1:8642/health +```console +$ curl -sf http://127.0.0.1:8642/health ``` If the command cannot connect after a reboot or terminal restart, start the forward again. -```bash -openshell forward start --background 8642 my-hermes +```console +$ openshell forward start --background 8642 my-hermes ``` Configure an OpenAI-compatible client with the base URL `http://127.0.0.1:8642/v1`. Hermes uses API header authentication for client requests. Do not append an OpenClaw `#token=` URL fragment to the Hermes endpoint. -Treat the dashboard as a local management UI. -Avoid exposing it on shared or public networks unless you put it behind your own access controls. - ## Manage the Sandbox Use the same lifecycle commands as a standard NemoClaw sandbox. The `nemohermes` alias keeps help text and recovery messages aligned with Hermes, while targeting the same registered sandbox. `nemoclaw list` shows the agent type for each sandbox so you can distinguish Hermes and OpenClaw entries. -```bash -nemohermes my-hermes status -nemohermes my-hermes logs --follow -nemohermes my-hermes snapshot create --name before-change -nemohermes my-hermes rebuild +```console +$ nemohermes my-hermes status +$ nemohermes my-hermes logs --follow +$ nemohermes my-hermes snapshot create --name before-change +$ nemohermes my-hermes rebuild ``` To change the active model or provider without rebuilding the sandbox, use `nemohermes inference set`. It updates the OpenShell inference route and patches `/sandbox/.hermes/config.yaml` without restarting Hermes. -```bash -nemohermes inference set --model --provider +```console +$ nemohermes inference set --model --provider ``` To remove the sandbox when you are done, destroy it explicitly. -```bash -nemohermes my-hermes destroy +```console +$ nemohermes my-hermes destroy ``` ## Next Steps diff --git a/skills/nemoclaw-user-get-started/references/windows-preparation.md b/skills/nemoclaw-user-get-started/references/windows-preparation.md index 95e0eec6c5..f3b87f30db 100644 --- a/skills/nemoclaw-user-get-started/references/windows-preparation.md +++ b/skills/nemoclaw-user-get-started/references/windows-preparation.md @@ -1,35 +1,19 @@ # Prepare Windows for NemoClaw -import { AgentOnly } from "../_components/AgentGuide"; - You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. - -Complete these steps before following the Quickstart. - - -Complete these steps before following Quickstart with Hermes. - +Complete these steps before following the [Quickstart](../SKILL.md). Linux and macOS users do not need this page and can go directly to the Quickstart. **Note:** -NVIDIA tested this guide on x86-64. +This guide has been tested on x86-64. ## Prerequisites Verify the following before you begin: - Windows 10 (build 19041 or later) or Windows 11. - - -- Hardware requirements are the same as the Quickstart. - - - - -- Hardware requirements are the same as Quickstart with Hermes. - - +- Hardware requirements are the same as the [Quickstart](../SKILL.md). ## Option: Use the Bootstrap Script @@ -43,8 +27,6 @@ The command downloads the script to a temporary file before running it. `-ExecutionPolicy Bypass` applies only to that PowerShell process and avoids local policy blocking the downloaded script. Run it from Windows, not from inside WSL. The script requests Administrator privileges when needed, enables the required WSL 2 Windows features, installs or opens Ubuntu 24.04, and installs and starts Docker Desktop. -When Ubuntu needs first-run account setup, the script opens a handoff window and waits for that account to exist before it changes Docker settings. -It enables Docker Desktop WSL integration for the target distro, restarts Docker Desktop only when Docker was already running, and leaves your global default WSL distro unchanged. If the target Ubuntu distro is already registered, the script confirms it uses WSL 2, converts it from WSL 1 when needed, and verifies Docker is reachable from WSL. If Windows requires a reboot after enabling WSL features, the script prompts for the reboot and registers a one-time continuation for the next sign-in. If Docker Desktop shows first-run prompts, complete them and return to the PowerShell window. @@ -61,11 +43,10 @@ When Windows preparation is complete, it opens Ubuntu and prints the standard in curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -If the bootstrap script reports that Ubuntu cannot reach Docker, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for Ubuntu (**Settings** > **Resources** > **WSL integration**), make sure Docker Desktop is running, then rerun the script. +If the bootstrap script reports that Docker is not reachable from Ubuntu, open Docker Desktop Settings and confirm that WSL integration is enabled for Ubuntu (Settings > Resources > WSL integration), then rerun the script. If the bootstrap script reports that `winget.exe` is not available (common on Windows Server or stripped Windows installs), install **App Installer** from the Microsoft Store (which provides `winget`), or download and install Docker Desktop manually from [docker.com](https://www.docker.com/products/docker-desktop/). -After you install Docker Desktop, rerun the bootstrap script. -The script skips the install step after it detects Docker Desktop. +Rerun the bootstrap script after Docker Desktop is installed; the script skips the install step once it detects Docker Desktop is present. The manual steps below describe the same Windows preparation pieces and are useful when you need to verify or repair WSL, Ubuntu, or Docker Desktop by hand. @@ -95,9 +76,9 @@ Let the distribution launch and complete first-run setup (pick a Unix username a Do not use the `--no-launch` flag. The `--no-launch` flag downloads the package but does not register the distribution with WSL. -Commands like `wsl -d Ubuntu-24.04` fail with "There is no distribution with the supplied name" until you launch the distribution at least one time. +Commands like `wsl -d Ubuntu-24.04` fail with "There is no distribution with the supplied name" until the distribution has been launched at least once. -Verify that WSL registered the distribution and runs it with WSL 2: +Verify the distribution is registered and running WSL 2: ```powershell wsl -l -v @@ -114,7 +95,7 @@ Expected output: Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the WSL 2 backend (the default on Windows 11). -After installation, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for your Ubuntu distribution (**Settings** > **Resources** > **WSL integration**). +After installation, open Docker Desktop Settings and confirm that WSL integration is enabled for your Ubuntu distribution (Settings > Resources > WSL integration). Open WSL from PowerShell: @@ -129,7 +110,7 @@ docker info ``` `docker info` prints server information. -If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that Docker Desktop enables WSL integration. +If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is running and that WSL integration is enabled. ## Set Up Local Inference with Ollama (Optional) @@ -140,7 +121,7 @@ You can install Ollama inside WSL yourself: curl -fsSL https://ollama.com/install.sh | sh ``` -If you installed Ollama but it is not already running in WSL, onboarding starts it for you. +If Ollama is installed but not already running in WSL, the onboarding process starts it for you. You can also start it yourself beforehand with `ollama serve`. You can also use Ollama for Windows. @@ -154,15 +135,10 @@ Use one instance, or move one of them to a different port before running `nemocl Your Windows environment is ready. If you used the bootstrap script, follow the installer command it printed inside Ubuntu. - -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the Quickstart to install NemoClaw and launch your first sandbox. - - -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with Quickstart with Hermes to install NemoClaw and launch your first Hermes sandbox. - +If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](../SKILL.md) to install NemoClaw and launch your first sandbox. All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, refer to the Windows Subsystem for Linux section in the Troubleshooting guide. +For Windows-specific troubleshooting, refer to the Windows Subsystem for Linux section (use the `nemoclaw-user-reference` skill) in the Troubleshooting guide. diff --git a/skills/nemoclaw-user-manage-policy/SKILL.md b/skills/nemoclaw-user-manage-policy/SKILL.md index cb1e41036e..298c672588 100644 --- a/skills/nemoclaw-user-manage-policy/SKILL.md +++ b/skills/nemoclaw-user-manage-policy/SKILL.md @@ -4,11 +4,13 @@ description: "Adds, removes, or modifies allowed endpoints in the sandbox policy license: "Apache-2.0" --- + + + # Customize the Sandbox Network Policy ## Gotchas -- Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match. - Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. ## Prerequisites @@ -16,11 +18,9 @@ license: "Apache-2.0" - A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes. - The OpenShell CLI on your `PATH`. -import { AgentOnly } from "../_components/AgentGuide"; - -Add, remove, or modify the endpoints the sandbox can reach. +Add, remove, or modify the endpoints that the sandbox is allowed to reach. -The NemoClaw repository defines the sandbox policy in a declarative YAML file, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime. +The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI. **Note:** @@ -30,34 +30,18 @@ Apply a custom NemoClaw preset with `nemoclaw policy-add --from-file`. Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime. See Agent cannot reach a host-side HTTP service (use the `nemoclaw-user-reference` skill). -**Warning:** - -Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match. -OpenShell still applies SSRF protection separately, so a request can be denied if the final address resolves to a loopback, private, link-local, or otherwise blocked internal range. -If a package installer or browser runtime download still fails with an SSRF-style denial after you add the public host, install that binary into the sandbox image at build time with `nemoclaw onboard --from` (use the `nemoclaw-user-reference` skill) instead of relying on runtime egress. - ## Static Changes Static changes modify the baseline policy file and take effect after the next sandbox creation. ### Edit the Policy File - Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `nemoclaw onboard`. If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit `openclaw-sandbox.yaml`. - - -Open the Hermes policy additions and shared sandbox policy files under `agents/hermes/` and `nemoclaw-blueprint/policies/`, then add or modify endpoint entries. - -If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `nemoclaw onboard`. - -If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). -That updates the live policy and does not edit the baseline policy files. - Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. @@ -76,18 +60,18 @@ Each entry in the `network` section defines an endpoint group with the following Apply the updated policy by re-running the onboard wizard: -```bash -nemoclaw onboard +```console +$ nemoclaw onboard ``` -The wizard reads the modified policy file and applies it to the sandbox. +The wizard picks up the modified policy file and applies it to the sandbox. ### Verify the Policy Check that the sandbox is running with the updated policy: -```bash -nemoclaw status +```console +$ nemoclaw status ``` ### Add Blueprint Policy Additions @@ -102,7 +86,7 @@ Dynamic changes apply a policy update to a running sandbox without restarting it > [!WARNING] > `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge. -> A running sandbox's live policy is the baseline policy plus every preset that was layered on during onboarding. +> A running sandbox's live policy is the baseline from `openclaw-sandbox.yaml` plus every preset that was layered on during onboarding. > Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect. ### Option 1: Drop a Preset File and Use `policy-add` (Recommended) @@ -132,46 +116,41 @@ This is the non-destructive path and the only flow NemoClaw supports out of the 2. Apply it to the running sandbox: -```bash -nemoclaw my-assistant policy-add -``` + ```console + $ nemoclaw my-assistant policy-add + ``` -NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. -Existing presets and the baseline remain in place. -The preset file under `presets/` also persists across sandbox recreations. + NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. + Existing presets and the baseline remain in place. + The preset file under `presets/` also persists across sandbox recreations. -### Option 2: Snapshot, Edit, and Set with OpenShell +### Option 2: Snapshot, Edit, and Set via OpenShell Use this path only when you cannot add a file under the NemoClaw source tree. -You must start from the **live** policy, not from a baseline policy file, so the presets layered on at onboarding are preserved in the file you apply. +You must start from the **live** policy, not from `openclaw-sandbox.yaml`, so the presets layered on at onboarding are preserved in the file you apply. -```bash -openshell policy get --full my-assistant > live-policy.yaml +```console +$ openshell policy get --full my-assistant > live-policy.yaml ``` Edit `live-policy.yaml` to add your entries under `network_policies:`, keeping the existing `version` field intact, then apply: -```bash -openshell policy set --policy live-policy.yaml my-assistant +```console +$ openshell policy set --policy live-policy.yaml my-assistant ``` ### Scope of Dynamic Changes 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`. - +When the sandbox stops, the running policy resets to the baseline composed from `openclaw-sandbox.yaml` 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`. ### Approve Requests Interactively For one-off access, you can approve blocked requests in the OpenShell TUI instead of editing the baseline policy: -```bash -openshell term +```console +$ openshell term ``` This is useful when you want to test a destination before deciding whether it belongs in a permanent preset or custom policy file. @@ -207,8 +186,8 @@ Available presets: To apply a preset to a running sandbox: -```bash -nemoclaw policy-add +```console +$ nemoclaw policy-add ``` **Note:** @@ -218,33 +197,29 @@ Pass a preset name with `--yes` for scripted workflows. For example, to interactively add PyPI access to a running sandbox: -```bash -nemoclaw my-assistant policy-add +```console +$ nemoclaw my-assistant policy-add ``` To list which presets are applied to a sandbox: -```bash -nemoclaw policy-list +```console +$ nemoclaw policy-list ``` - To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. - - -To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemoclaw onboard`. - **Note:** -The `openshell policy set --policy ` command operates on raw policy files and does not accept the `preset:` metadata block used in preset YAML files. -Use `nemoclaw policy-add` for presets. +The `openshell policy set --policy ` command operates on raw policy files and does not +accept the `preset:` metadata block used in preset YAML files. Use `nemoclaw policy-add` for +presets. For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument: -```bash -nemoclaw my-assistant policy-add pypi --yes -nemoclaw my-assistant policy-remove pypi --yes +```console +$ nemoclaw my-assistant policy-add pypi --yes +$ nemoclaw my-assistant policy-remove pypi --yes ``` Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable. @@ -283,16 +258,16 @@ Rename `preset.name` if NemoClaw refuses to apply the file because of a collisio ### Apply a Single File -```bash -nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml +```console +$ nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. ### Apply Every File in a Directory -```bash -nemoclaw my-assistant policy-add --from-dir ./presets/ --yes +```console +$ nemoclaw my-assistant policy-add --from-dir ./presets/ --yes ``` Files are processed in lexicographic order. @@ -304,21 +279,13 @@ Fix the failing file and re-run the command to continue. Custom preset hosts bypass NemoClaw's review process and can widen sandbox egress to arbitrary destinations. Review every host in a custom preset before applying it, especially when the file originates outside your team. -### Remove a Custom Preset - -NemoClaw records custom presets applied with `--from-file` or `--from-dir` in the sandbox registry alongside their full YAML content. -You can remove them by name without keeping the original file on disk: - -```bash -nemoclaw my-assistant policy-remove my-internal-api --yes -``` - -`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. +Load [references/customize-network-policy-details.md](references/customize-network-policy-details.md) for detailed steps on Remove a Custom Preset. ## References - **[references/integration-policy-examples.md](references/integration-policy-examples.md)** — Guides users through common post-install integration policy setup for maintained NemoClaw policy presets, including Outlook, messaging channels, GitHub, Jira, Brave Search, package managers, Hugging Face, local inference, and OpenShell approval workflows. - **Load [references/approve-network-requests.md](references/approve-network-requests.md)** when approving or denying sandbox egress requests, managing blocked network calls, or using the approval TUI. Reviews and approves blocked agent network requests in the TUI. +- **Load [references/customize-network-policy-details.md](references/customize-network-policy-details.md)** when you need detailed steps for Remove a Custom Preset. ## Related Skills diff --git a/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md b/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md index 6c97de9f7c..bb1e73d494 100644 --- a/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md +++ b/skills/nemoclaw-user-manage-policy/references/approve-network-requests.md @@ -1,3 +1,5 @@ + + # Approve or Deny Agent Network Requests Review and act on network requests that the agent makes to endpoints not listed in the sandbox policy. @@ -12,14 +14,14 @@ OpenShell intercepts these requests and presents them in the TUI for operator ap Start the OpenShell terminal UI to monitor sandbox activity: -```bash -openshell term +```console +$ openshell term ``` For a remote sandbox, pass the instance name: -```bash -ssh my-gpu-box 'cd ~/nemoclaw && . .env && openshell term' +```console +$ ssh my-gpu-box 'cd ~/nemoclaw && . .env && openshell term' ``` The TUI displays the sandbox state, active inference provider, and a live feed of network activity. @@ -48,8 +50,8 @@ To keep an endpoint allowed after a restart, update the policy YAML or apply a p From the NemoClaw repository root, run the walkthrough script after you have onboarded at least one sandbox and it is reachable: -```bash -./scripts/walkthrough.sh +```console +$ ./scripts/walkthrough.sh ``` This script opens a split tmux session with the TUI on the left and the agent on the right. diff --git a/skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md b/skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md new file mode 100644 index 0000000000..224829b964 --- /dev/null +++ b/skills/nemoclaw-user-manage-policy/references/customize-network-policy-details.md @@ -0,0 +1,13 @@ + + +# Customize the Sandbox Network Policy: Details + +## Remove a Custom Preset + +Custom presets applied with `--from-file` or `--from-dir` are recorded in the NemoClaw sandbox registry alongside their full YAML content, so they can be removed by name — the original file does not need to be kept on disk: + +```console +$ nemoclaw my-assistant policy-remove my-internal-api --yes +``` + +`policy-remove` accepts both built-in and custom preset names. Run `nemoclaw policy-list` to see every preset currently applied to the sandbox. diff --git a/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md b/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md index f28f5dff5f..db1c12d1db 100644 --- a/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md +++ b/skills/nemoclaw-user-manage-policy/references/integration-policy-examples.md @@ -1,7 +1,7 @@ + + # Common NemoClaw Integration Policy Examples -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/`. Integration setup usually has two separate parts: @@ -18,19 +18,19 @@ Replace `my-assistant` with your sandbox name in the examples. Check the current policy state first: -```bash -nemoclaw my-assistant policy-list +```console +$ nemoclaw my-assistant policy-list ``` For a live view of blocked requests, open the OpenShell TUI in a separate host terminal: -```bash -openshell term +```console +$ openshell term ``` When the agent reaches an endpoint that is not in policy, the TUI shows the host, port, requesting binary, method, and path when available. Approve a request only when you understand why the integration needs it. -An approval updates the running policy, but it does not create a reviewable NemoClaw preset entry that `policy-add` can replay. +An approval updates the running policy, but it does not create a NemoClaw preset entry that can be reviewed and replayed like `policy-add`. ## Supported Integration Presets @@ -48,30 +48,28 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr | OpenClaw model-pricing reference fetch | `openclaw-pricing` | | npm and Yarn packages | `npm` | | Microsoft 365, Outlook, and Graph API | `outlook` | -| Public reference APIs | `public-reference` | | Python Package Index | `pypi` | | Slack messaging | `slack` | | Telegram Bot API | `telegram` | -| Weather and geocoding APIs | `weather` | | WeChat (personal) iLink Bot API (experimental) | `wechat` | | WhatsApp Web messaging (experimental) | `whatsapp` | Preview the endpoints before applying: -```bash -nemoclaw my-assistant policy-add outlook --dry-run +```console +$ nemoclaw my-assistant policy-add outlook --dry-run ``` Apply the preset: -```bash -nemoclaw my-assistant policy-add outlook --yes +```console +$ nemoclaw my-assistant policy-add outlook --yes ``` Remove it later if the sandbox no longer needs that access: -```bash -nemoclaw my-assistant policy-remove outlook --yes +```console +$ nemoclaw my-assistant policy-remove outlook --yes ``` ## Email and Calendar With Microsoft 365 @@ -79,9 +77,9 @@ nemoclaw my-assistant policy-remove outlook --yes Use the `outlook` preset for Microsoft 365 email and calendar workflows that use Microsoft Graph or Outlook endpoints. The preset allows `graph.microsoft.com`, Microsoft login, and Outlook service endpoints. -```bash -nemoclaw my-assistant policy-add outlook --dry-run -nemoclaw my-assistant policy-add outlook --yes +```console +$ nemoclaw my-assistant policy-add outlook --dry-run +$ nemoclaw my-assistant policy-add outlook --yes ``` Then configure the email or calendar tool credentials through the integration you are running in the sandbox. @@ -95,23 +93,23 @@ If the blocked endpoint is not covered by the maintained `outlook` preset, treat Telegram needs both channel configuration and egress policy. If you already enabled Telegram during onboarding but did not include the preset, add it to the running sandbox: -```bash -nemoclaw my-assistant policy-add telegram --yes +```console +$ nemoclaw my-assistant policy-add telegram --yes ``` To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and make sure the policy preset is applied: -```bash -export TELEGRAM_BOT_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add telegram --yes +```console +$ export TELEGRAM_BOT_TOKEN= +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add telegram --yes ``` If delivery fails, open the TUI and send a test message to the bot: -```bash -openshell term +```console +$ openshell term ``` The matching preset for each supported messaging channel is the channel name (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`). @@ -123,61 +121,60 @@ Use the matching policy preset after you configure the channel credentials. For Slack: -```bash -export SLACK_BOT_TOKEN= -export SLACK_APP_TOKEN= -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add slack --yes +```console +$ export SLACK_BOT_TOKEN= +$ export SLACK_APP_TOKEN= +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add slack --yes ``` For Discord: -```bash -export DISCORD_BOT_TOKEN= -export DISCORD_SERVER_ID= -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add discord --yes +```console +$ export DISCORD_BOT_TOKEN= +$ export DISCORD_SERVER_ID= +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add discord --yes ``` If you enabled Slack or Discord during onboarding, apply only the matching preset: -```bash -nemoclaw my-assistant policy-add slack --yes -nemoclaw my-assistant policy-add discord --yes +```console +$ nemoclaw my-assistant policy-add slack --yes +$ nemoclaw my-assistant policy-add discord --yes ``` ## WeChat or WhatsApp Messaging (Experimental) WeChat and WhatsApp are experimental. -Both rely on QR-based pairing flows that are more fragile than token-based bots. -The upstream client libraries can change behavior without notice. +Both rely on QR-based pairing flows that are more fragile than token-based bots, and the upstream client libraries can change behavior without notice. WeChat uses Tencent's iLink Bot API for personal accounts. The bot token is captured by a host-side QR scan during onboarding rather than pasted from a developer portal. Add the channel interactively and apply the preset: -```bash -nemoclaw my-assistant channels add wechat -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add wechat --yes +```console +$ nemoclaw my-assistant channels add wechat +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add wechat --yes ``` -WhatsApp Web pairs entirely inside the sandbox through QR scan, so `channels add` does not collect a host-side token. +WhatsApp Web pairs entirely inside the sandbox via QR scan, so `channels add` does not collect a host-side token. Apply the preset and complete the in-sandbox pairing after the rebuild: -```bash -NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp -nemoclaw my-assistant rebuild -nemoclaw my-assistant policy-add whatsapp --yes +```console +$ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp +$ nemoclaw my-assistant rebuild +$ nemoclaw my-assistant policy-add whatsapp --yes ``` If you enabled WeChat or WhatsApp during onboarding, apply only the matching preset: -```bash -nemoclaw my-assistant policy-add wechat --yes -nemoclaw my-assistant policy-add whatsapp --yes +```console +$ nemoclaw my-assistant policy-add wechat --yes +$ nemoclaw my-assistant policy-add whatsapp --yes ``` ## GitHub and Jira @@ -187,38 +184,37 @@ Use `jira` when the agent needs Atlassian Jira access. Preview first: -```bash -nemoclaw my-assistant policy-add github --dry-run -nemoclaw my-assistant policy-add jira --dry-run +```console +$ nemoclaw my-assistant policy-add github --dry-run +$ nemoclaw my-assistant policy-add jira --dry-run ``` Apply the preset that matches the workflow: -```bash -nemoclaw my-assistant policy-add github --yes -nemoclaw my-assistant policy-add jira --yes +```console +$ nemoclaw my-assistant policy-add github --yes +$ nemoclaw my-assistant policy-add jira --yes ``` The `jira` preset intentionally allows Node.js access to Atlassian Cloud and does not allow `curl`. When validating it manually, avoid plain `curl -s` against `auth.atlassian.com`. Atlassian can return an empty redirect body even when the request succeeds. -Use a body-visible API probe instead: +Use an explicit status probe instead: -```bash -node -e "require('https').get('https://api.atlassian.com', r => console.log(r.statusCode))" -curl -sS --max-time 10 -w '\n%{http_code}\n' https://api.atlassian.com/oauth/token/accessible-resources +```console +$ node -e "require('https').get('https://api.atlassian.com', r => console.log(r.statusCode))" +$ curl -sS -o /dev/null -w '%{http_code}' --max-time 10 https://auth.atlassian.com ``` Before approval, the curl probe should report `000` or a local policy denial. -After explicitly approving curl for `api.atlassian.com` in OpenShell, it should return Atlassian's unauthenticated `401` JSON response. -That `401` is the expected success signal for this manual probe. -This manual probe proves curl reached Atlassian, but no Jira credentials were supplied. +After approving the blocked request in OpenShell, it should report an HTTP +status such as `301` or `200`. Remove access when the task is done: -```bash -nemoclaw my-assistant policy-remove github --yes -nemoclaw my-assistant policy-remove jira --yes +```console +$ nemoclaw my-assistant policy-remove github --yes +$ nemoclaw my-assistant policy-remove jira --yes ``` ## Brave Search @@ -226,32 +222,13 @@ nemoclaw my-assistant policy-remove jira --yes The default Balanced policy tier includes `brave`. If you chose Restricted during onboarding or removed the preset later, add it before enabling Brave Search workflows: -```bash -nemoclaw my-assistant policy-add brave --dry-run -nemoclaw my-assistant policy-add brave --yes +```console +$ nemoclaw my-assistant policy-add brave --dry-run +$ nemoclaw my-assistant policy-add brave --yes ``` The Brave Search API key is still configured separately during onboarding or through the web search setup flow. -## Weather and Public Reference Lookups - -Use the `weather` preset when the agent needs read-only weather or geocoding lookups. -The Balanced and Open tiers include it by default. -The preset covers Open-Meteo, geocoding, and National Weather Service endpoints without enabling messaging or productivity APIs. - -```bash -nemoclaw my-assistant policy-add weather --dry-run -nemoclaw my-assistant policy-add weather --yes -``` - -Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. -The Open tier includes this preset by default. - -```bash -nemoclaw my-assistant policy-add public-reference --dry-run -nemoclaw my-assistant policy-add public-reference --yes -``` - ## Package and Model Tooling Use these presets when an agent workflow installs packages or downloads model assets: @@ -259,50 +236,43 @@ Use these presets when an agent workflow installs packages or downloads model as | Workflow | Preset | |----------|--------| | npm or Yarn packages | `npm` | -| Python packages from PyPI with `pip`, Python, or `uv` | `pypi` | +| Python packages from PyPI | `pypi` | | Homebrew packages | `brew` | | Hugging Face model or dataset access | `huggingface` | Add only the preset required for the task: -```bash -nemoclaw my-assistant policy-add npm --yes -nemoclaw my-assistant policy-add pypi --yes -nemoclaw my-assistant policy-add brew --yes -nemoclaw my-assistant policy-add huggingface --yes +```console +$ nemoclaw my-assistant policy-add npm --yes +$ nemoclaw my-assistant policy-add pypi --yes +$ nemoclaw my-assistant policy-add brew --yes +$ nemoclaw my-assistant policy-add huggingface --yes ``` Remove package access after a one-time setup task if the sandbox no longer needs it: -```bash -nemoclaw my-assistant policy-remove npm --yes -nemoclaw my-assistant policy-remove pypi --yes -nemoclaw my-assistant policy-remove brew --yes -nemoclaw my-assistant policy-remove huggingface --yes +```console +$ nemoclaw my-assistant policy-remove npm --yes +$ nemoclaw my-assistant policy-remove pypi --yes +$ nemoclaw my-assistant policy-remove brew --yes +$ nemoclaw my-assistant policy-remove huggingface --yes ``` -The `pypi` preset allows Python, `pip`, virtual-environment Python and `pip`, and `/usr/local/bin/uv` to reach PyPI endpoints. -If `uv` is installed somewhere else in the sandbox, add a custom preset for that binary path instead of broadening the maintained preset locally. - ### Homebrew Specifics The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` preset is the only step needed before installing a formula. -A `/usr/local/bin/brew` wrapper puts the entry point on the sandbox `PATH` while delegating to the Linuxbrew prefix. -Installed formula commands are available from the Linuxbrew bin directory in sandbox shell sessions: +A `/usr/local/bin/brew` symlink puts the entry point on the sandbox `PATH`, so the agent can run `brew install ` directly: -```bash -nemoclaw my-assistant policy-add brew --yes -nemoclaw my-assistant exec -- brew install -nemoclaw my-assistant exec -- bash -lc '' +```console +$ nemoclaw my-assistant policy-add brew --yes +$ nemoclaw my-assistant exec -- brew install ``` You do not need to bootstrap Homebrew, install build dependencies, or source `brew shellenv` inside the sandbox. ## Model Pricing - - -OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter on every start to populate `usage.cost` in session JSONL records. +OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter on every start so it can populate `usage.cost` in session JSONL records. The default-strict egress policy denies both hosts. The fetch fails closed, the gateway logs `[gateway/model-pricing] LiteLLM pricing fetch failed: TypeError: fetch failed` (and the matching OpenRouter line) on every startup, and every session record records `usage.cost = 0` even though the input and output token counts populate correctly. Tools that read the session log to display per-turn cost (audit dashboards, compliance review surfaces) cannot distinguish a real free run from this silent failure. @@ -310,19 +280,12 @@ Tools that read the session log to display per-turn cost (audit dashboards, comp Apply the `openclaw-pricing` preset to allow both pricing endpoints. The preset pins each host to a single read-only path so it does not widen egress beyond the pricing fetch: -```bash -nemoclaw my-assistant policy-add openclaw-pricing --dry-run -nemoclaw my-assistant policy-add openclaw-pricing --yes +```console +$ nemoclaw my-assistant policy-add openclaw-pricing --dry-run +$ nemoclaw my-assistant policy-add openclaw-pricing --yes ``` -After the next gateway restart, the WARN entries stop and `usage.cost` populates from the fetched pricing tables. - - - - -Hermes does not use OpenClaw's model-pricing reference fetch. - - +After the next gateway restart the WARN entries stop and `usage.cost` populates from the fetched pricing tables. ## Local Inference @@ -330,35 +293,35 @@ Use `local-inference` when the sandbox needs access to host-side local inference Onboarding auto-suggests this preset when you choose a local provider. If you need to add it after onboarding: -```bash -nemoclaw my-assistant policy-add local-inference --dry-run -nemoclaw my-assistant policy-add local-inference --yes +```console +$ nemoclaw my-assistant policy-add local-inference --dry-run +$ nemoclaw my-assistant policy-add local-inference --yes ``` Then verify the sandbox status: -```bash -nemoclaw my-assistant status +```console +$ nemoclaw my-assistant status ``` ## Inspect or Replace the Live Policy Use `policy-list` for normal preset state: -```bash -nemoclaw my-assistant policy-list +```console +$ nemoclaw my-assistant policy-list ``` Use OpenShell when you need the full enforced YAML: -```bash -openshell policy get --full my-assistant > live-policy.yaml +```console +$ openshell policy get --full my-assistant > live-policy.yaml ``` If you must replace the live policy, edit the full policy file and set it back: -```bash -openshell policy set --policy live-policy.yaml my-assistant --wait +```console +$ openshell policy set --policy live-policy.yaml my-assistant --wait ``` `openshell policy set` replaces the live policy with the file you provide. diff --git a/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/skills/nemoclaw-user-manage-sandboxes/SKILL.md index bc81066f59..b5618052c5 100644 --- a/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -1,89 +1,75 @@ --- name: "nemoclaw-user-manage-sandboxes" -description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, install hermes plugins, hermes plugins nemoclaw, nemoclaw hermes plugins, nemohermes dockerignore, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." +description: "Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence." license: "Apache-2.0" --- -# Manage Sandbox Lifecycle + + -import { AgentOnly } from "../_components/AgentGuide"; +# Manage Sandbox Lifecycle - Use this guide after you finish the OpenClaw quickstart (use the `nemoclaw-user-get-started` skill). - - -Use this guide after you finish Quickstart with Hermes (use the `nemoclaw-user-get-started` skill). - It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. - When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw` and `openshell`. - - -When a workflow uses the lower-level OpenShell CLI, see CLI Selection Guide (use the `nemoclaw-user-reference` skill) for the boundary between `nemoclaw`, `nemoclaw`, and `openshell`. - ## List Sandboxes List every sandbox registered on this host: -```bash -nemoclaw list +```console +$ nemoclaw list ``` -The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when NemoClaw records a dashboard port. +The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when a dashboard port is recorded. Use JSON output for scripts: -```bash -nemoclaw list --json +```console +$ nemoclaw list --json ``` ## Check Sandbox Health Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings: -```bash -nemoclaw my-assistant status +```console +$ nemoclaw my-assistant status ``` Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared: -```bash -nemoclaw status +```console +$ nemoclaw status ``` ## Inspect Logs View recent sandbox logs: -```bash -nemoclaw my-assistant logs +```console +$ nemoclaw my-assistant logs ``` Stream logs while you reproduce a problem: -```bash -nemoclaw my-assistant logs --follow +```console +$ nemoclaw my-assistant logs --follow ``` - The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs. - - -The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs. - ## Collect Diagnostics Collect diagnostics for bug reports or support handoff: -```bash -nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz +```console +$ nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` Use `--quick` for a smaller local summary: -```bash -nemoclaw debug --quick --sandbox my-assistant +```console +$ nemoclaw debug --quick --sandbox my-assistant ``` The debug command gathers system information, Docker state, gateway logs, and sandbox status. @@ -92,46 +78,37 @@ The debug command gathers system information, Docker state, gateway logs, and sa If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart it manually with the port from the install summary. -```bash -openshell forward start --background my-gpt-claw +```console +$ openshell forward start --background my-gpt-claw ``` To list active forwards across all sandboxes, run the following command. -```bash -openshell forward list +```console +$ openshell forward list ``` ## Run Multiple Sandboxes Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. - When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. - - -When the default API port is already held by another sandbox, `nemoclaw onboard` scans for the next free port and records it for the sandbox. - -If you intentionally run separate OpenShell gateways on the same host, set a different `NEMOCLAW_GATEWAY_PORT` before each onboarding run. -NemoClaw isolates the gateway name and local state by port so one port-specific gateway does not replace another. -Gateway and dashboard cleanup is scoped by sandbox name and port. -A later onboarding run that uses a different `NEMOCLAW_GATEWAY_PORT` or `--control-ui-port` does not tear down the first sandbox's gateway or dashboard forward. -```bash -nemoclaw onboard # first sandbox uses 18789 -nemoclaw onboard # second sandbox uses the next free port, such as 18790 +```console +$ nemoclaw onboard # first sandbox uses 18789 +$ nemoclaw onboard # second sandbox uses the next free port, such as 18790 ``` To choose a specific port, pass `--control-ui-port`: -```bash -nemoclaw onboard --control-ui-port 19000 +```console +$ nemoclaw onboard --control-ui-port 19000 ``` You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding: -```bash -CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard -NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard +```console +$ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard +$ NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard ``` For full details on port conflicts and overrides, refer to Port already in use (use the `nemoclaw-user-reference` skill). @@ -144,23 +121,18 @@ Recover from a misconfigured sandbox without re-running the full onboard wizard Change the active model or provider at runtime without rebuilding the sandbox: -```bash -nemoclaw inference set --model --provider +```console +$ nemoclaw inference set --model --provider ``` Refer to Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward - If `nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. - - -If `nemoclaw status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. - -```bash -nemoclaw recover +```console +$ nemoclaw recover ``` The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step. @@ -169,27 +141,22 @@ Refer to `nemoclaw recover` (use the `nemoclaw-user-reference` skill) for ### Reset a Stored Credential -If you entered a provider credential incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: +If a provider credential was entered incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: -```bash -nemoclaw credentials list # see which providers are registered -nemoclaw credentials reset # clear a single provider, for example nvidia-prod -nemoclaw onboard # re-run to re-enter the cleared provider +```console +$ nemoclaw credentials list # see which providers are registered +$ nemoclaw credentials reset # clear a single provider, for example nvidia-prod +$ nemoclaw onboard # re-run to re-enter the cleared provider ``` -The command reference documents `nemoclaw credentials reset ` (use the `nemoclaw-user-reference` skill) in full. +The credentials command is documented in full at `nemoclaw credentials reset ` (use the `nemoclaw-user-reference` skill). ### Rebuild a Sandbox While Preserving Workspace State - If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating: - - -If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox's state files, use `rebuild` instead of destroying and recreating: - -```bash -nemoclaw rebuild +```console +$ nemoclaw rebuild ``` Rebuild preserves the mounted workspace and registered policies while recreating the container. @@ -200,8 +167,8 @@ Refer to `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill) for Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding: -```bash -nemoclaw policy-add +```console +$ nemoclaw policy-add ``` Refer to `nemoclaw policy-add` (use the `nemoclaw-user-reference` skill) for usage details and flags. @@ -210,30 +177,48 @@ Non-interactive re-onboards in the default `suggested` policy mode preserve pres To make a re-onboard authoritative, set `NEMOCLAW_POLICY_MODE=custom` and provide `NEMOCLAW_POLICY_PRESETS` with the exact list to apply; onboarding removes anything else. See `NEMOCLAW_POLICY_MODE` (use the `nemoclaw-user-reference` skill) for the full table. -## Update to the Maintained Version +## Update to the Latest Version -When a maintained NemoClaw release becomes available, update the host CLI and then check whether existing sandboxes need rebuilds. -The standard installer follows the admin-promoted `lkg` release tag by default. -If you need a specific release, set `NEMOCLAW_INSTALL_TAG` on the `bash` side of the install pipeline. +When a new NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions. -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_INSTALL_TAG=v0.0.56 bash -nemoclaw upgrade-sandboxes --check +### Update the NemoClaw CLI + +Re-run the installer. +Before it onboards anything, the installer calls `nemoclaw backup-all` (use the `nemoclaw-user-reference` skill) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. +If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path. +The automatic path is offered only when the existing `nemoclaw` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway. +For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all` and `openshell gateway destroy -g nemoclaw || openshell gateway destroy` before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. + +```console +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -Before upgrade work, the installer runs `nemoclaw backup-all` when the installed CLI supports it. -For manual upgrade flows, create a snapshot first and then run the update or rebuild command you need: +### Upgrade Sandboxes with Stale Agent and Runtime Versions -```bash -nemoclaw snapshot create --name pre-upgrade -nemoclaw update --yes -nemoclaw upgrade-sandboxes --check +The installer checks registered sandboxes after onboarding succeeds and runs `nemoclaw upgrade-sandboxes --auto` for stale running sandboxes. +Use `upgrade-sandboxes` directly to verify the result, rebuild when you skipped the installer or onboarding step, or handle sandboxes that were stopped or could not be version-checked. +The upgrade flow is non-destructive by default because NemoClaw preserves manifest-defined workspace state, but a manual snapshot before any major upgrade gives you a state restore point. + +```console +$ nemoclaw snapshot create --name pre-upgrade # optional, recommended +$ nemoclaw update --yes # updates CLI through the maintained installer flow +$ nemoclaw upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes +$ nemoclaw upgrade-sandboxes # manually rebuild remaining stale running sandboxes +``` + +`nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. +Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. + +For scripted manual rebuilds, use `nemoclaw upgrade-sandboxes --auto` to skip the confirmation prompt. + +If the upgraded sandbox needs its workspace state reverted, restore the pre-upgrade snapshot into the running sandbox. +This restores saved state directories only; it does not downgrade the sandbox image or agent/runtime: + +```console +$ nemoclaw snapshot restore pre-upgrade ``` -Each rebuild destroys the old container and creates a new one, while preserving the manifest-defined workspace or agent state that NemoClaw knows how to snapshot. -Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved. -For the full state-preservation contract, snapshot restore behavior, and manual backup workflow, refer to [Backup and Restore](references/backup-restore.md). -For command flags, refer to `nemoclaw update` (use the `nemoclaw-user-reference` skill), `nemoclaw upgrade-sandboxes` (use the `nemoclaw-user-reference` skill), and `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill). +Load [references/lifecycle-details.md](references/lifecycle-details.md) for detailed steps on What Changes During a Rebuild. ## Uninstall @@ -249,17 +234,9 @@ nemoclaw uninstall | `--keep-openshell` | Leave OpenShell binaries installed. | | `--delete-models` | Also remove NemoClaw-pulled Ollama models. | -**Note:** - -The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots that snapshot and `backup-all` commands write), `~/.nemoclaw/backups/` (workspace backups that `scripts/backup-workspace.sh` writes), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default. -Uninstall removes every other entry under `~/.nemoclaw/`. -Interactive runs prompt before they remove the preserved entries; the default answer keeps them. -For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well. -See the Commands reference (use the `nemoclaw-user-reference` skill) for the full preservation contract. - -The CLI uninstall command runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. +`nemoclaw uninstall` runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. -If the CLI is missing or broken, fall back to the hosted script: +If the `nemoclaw` CLI is missing or broken, fall back to the hosted script: ```bash curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash @@ -271,15 +248,15 @@ The same `--yes`, `--keep-openshell`, and `--delete-models` flags listed above a curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes --delete-models ``` -For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, refer to `nemoclaw uninstall` vs. the hosted `uninstall.sh` (use the `nemoclaw-user-reference` skill). +For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, see `nemoclaw uninstall` vs. the hosted `uninstall.sh` (use the `nemoclaw-user-reference` skill). ## References - **[references/runtime-controls.md](references/runtime-controls.md)** — Single page that answers what can change at runtime versus what requires a rebuild for NemoClaw sandboxes. - **Load [references/backup-restore.md](references/backup-restore.md)** when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds. Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds. - **Load [references/messaging-channels.md](references/messaging-channels.md)** when setting up messaging channels, chat interfaces, or integrations without relying on nemoclaw tunnel start for bridges. Explains how Telegram, Discord, Slack, WeChat, and WhatsApp reach sandboxed OpenClaw and Hermes agents through OpenShell-managed processes and NemoClaw channel commands. -- **Load [references/install-plugins-hermes.md](references/install-plugins-hermes.md)** when users ask how to install, build, or configure Hermes plugins under NemoClaw. Explains how to install Hermes plugins in NemoClaw-managed sandboxes, including custom Dockerfile build-directory layout and `.dockerignore` handling. - **Load [references/workspace-files.md](references/workspace-files.md)** when users ask about `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, or other workspace files, or when preparing to back up or restore workspace state. Explains what workspace personality and configuration files are, where they live, and how they persist across sandbox restarts. +- **Load [references/lifecycle-details.md](references/lifecycle-details.md)** when you need detailed steps for What Changes During a Rebuild. ## Related Skills diff --git a/skills/nemoclaw-user-manage-sandboxes/evals/evals.json b/skills/nemoclaw-user-manage-sandboxes/evals/evals.json index 9553812c3f..ff6af55509 100644 --- a/skills/nemoclaw-user-manage-sandboxes/evals/evals.json +++ b/skills/nemoclaw-user-manage-sandboxes/evals/evals.json @@ -31,9 +31,9 @@ }, { "id": "docs-manage-sandboxes-runtime-controls-003", - "question": "I'm responding to an incident or risky agent behavior. Help me inspect runtime controls and choose the safest recovery path without confusion.", + "question": "I'm responding to an incident or risky agent behavior. Help me use `shields up`, `shields down`, and `shields status` correctly so I can tighten or inspect controls without confusion.", "expected_skill": "nemoclaw-user-manage-sandboxes", - "ground_truth": "A NemoClaw-specific answer that helps the user inspect runtime controls and choose the safest recovery path and gives enough concrete guidance, decision criteria, verification steps, or risk framing to avoid confusion." + "ground_truth": "A NemoClaw-specific answer that helps the user use `shields up`, `shields down`, and `shields status` correctly and gives enough concrete guidance, decision criteria, verification steps, or risk framing to tighten or inspect controls without confusion." }, { "id": "docs-manage-sandboxes-backup-restore-001", diff --git a/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md b/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md index ccebd8b589..70da806410 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/backup-restore.md @@ -1,157 +1,103 @@ + + # Backup and Restore Workspace Files -import { AgentOnly } from "../_components/AgentGuide"; - -Workspace and state files define your agent's personality, memory, user context, and durable runtime state. -They persist across sandbox restarts but are **permanently deleted** when you destroy the sandbox. +Workspace files define your agent's personality, memory, and user context. +They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. This guide covers snapshot commands, manual backup with CLI commands, and an automated script. ## When to Back Up - - -- Before running `nemoclaw destroy` +- **Before running `nemoclaw destroy`** - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent - - - -- Before running `nemoclaw destroy` -- Before major NemoClaw version upgrades -- Periodically, if you've invested time customizing your agent or paired messaging channels - - - ## Snapshot Commands The fastest way to back up and restore sandbox state is with the built-in snapshot commands. Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups//`. -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. - -```bash -nemoclaw my-assistant snapshot create -nemoclaw my-assistant snapshot list -nemoclaw my-assistant snapshot restore +Agent manifests may 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. + +```console +$ nemoclaw my-assistant snapshot create +$ nemoclaw my-assistant snapshot list +$ nemoclaw my-assistant snapshot restore ``` -`snapshot list` prints a table of version, name, timestamp, and path. -NemoClaw computes versions (`v1`, `v2`, ..., `vN`) from timestamp order, so `vN` is always the newest snapshot. +`snapshot list` prints a table of version, name, timestamp, and path. Versions (`v1`, `v2`, ..., `vN`) are computed from the timestamp order, so `vN` is always the newest snapshot. To tag a snapshot with a human-readable label, pass `--name`: -```bash -nemoclaw my-assistant snapshot create --name before-upgrade +```console +$ nemoclaw my-assistant snapshot create --name before-upgrade ``` To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix: -```bash -nemoclaw my-assistant snapshot restore v3 -nemoclaw my-assistant snapshot restore before-upgrade -nemoclaw my-assistant snapshot restore 2026-04-14T +```console +$ nemoclaw my-assistant snapshot restore v3 +$ nemoclaw my-assistant snapshot restore before-upgrade +$ nemoclaw my-assistant snapshot restore 2026-04-14T ``` To clone a snapshot into a different sandbox name, pass `--to `. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`: -```bash -nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone -nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes +```console +$ nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone +$ nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes ``` - - -The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. -Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that older images created. -NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. - - - - The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. -NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. +Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that were created by older images. +Unsafe symlinks and hard links inside sandbox state are rejected during backup creation before they can enter a snapshot. Credential-bearing Hermes files such as `auth.json` are intentionally excluded from snapshots. NemoClaw-regenerated Hermes config files (`config.yaml` and `.env`) are also excluded; model/provider and messaging credentials are recreated from host-side onboarding and OpenShell provider state during rebuild. - - For full details, see the Commands reference (use the `nemoclaw-user-reference` skill). ## Manual Backup Use `openshell sandbox download` to copy files from the sandbox to your host. - - -```bash -SANDBOX=my-assistant -BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) -mkdir -p "$BACKUP_DIR" - -openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" -``` - - - - -```bash -SANDBOX=my-hermes -BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) -mkdir -p "$BACKUP_DIR" - -openshell sandbox download "$SANDBOX" /sandbox/SOUL.md "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.hermes/state.db "$BACKUP_DIR/" -openshell sandbox download "$SANDBOX" /sandbox/.hermes/platforms/ "$BACKUP_DIR/platforms/" +```console +$ SANDBOX=my-assistant +$ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +$ mkdir -p "$BACKUP_DIR" + +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/SOUL.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/USER.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/IDENTITY.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/AGENTS.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" ``` - - ## Manual Restore Use `openshell sandbox upload` to push files back into a sandbox. - - -```bash -SANDBOX=my-assistant -BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp - -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ -``` - - - - -```bash -SANDBOX=my-hermes -BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp - -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/state.db" /sandbox/.hermes/ -openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/platforms/ +```console +$ SANDBOX=my-assistant +$ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/USER.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/IDENTITY.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/AGENTS.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw/workspace/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ ``` - - ## Using the Backup Script - - The repository includes a convenience script at `scripts/backup-workspace.sh`. ### Backup @@ -166,14 +112,14 @@ Backup saved to /home/user/.nemoclaw/backups/20260320-120000/ (6 items) Restore from the most recent backup: -```bash -./scripts/backup-workspace.sh restore my-assistant +```console +$ ./scripts/backup-workspace.sh restore my-assistant ``` Restore from a specific timestamp: -```bash -./scripts/backup-workspace.sh restore my-assistant 20260320-120000 +```console +$ ./scripts/backup-workspace.sh restore my-assistant 20260320-120000 ``` ## Verifying a Backup @@ -190,47 +136,31 @@ USER.md memory/ ``` - - - -For Hermes, prefer the built-in snapshot commands for faithful restore of `state.db`. -Use manual `openshell sandbox download` / `openshell sandbox upload` only when you need to inspect or transfer a specific file. - - - - - ## Multi-Agent Deployments -When you configure OpenClaw with multiple named agents, each agent has its own workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, and so on). -Refer to [Multi-Agent Deployments](workspace-files.md#multi-agent-deployments). +When OpenClaw is configured with multiple named agents, each agent has its own +workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, +and so on — see [Multi-Agent Deployments](workspace-files.md#multi-agent-deployments)). -`nemoclaw snapshot create` automatically discovers every `workspace-*/` directory under the sandbox state tree and includes it in the snapshot bundle alongside the default `workspace/`. -`snapshot restore` reapplies the full per-agent set. -You do not need a manual per-workspace backup pattern. +`nemoclaw snapshot create` automatically discovers every `workspace-*/` +directory under the sandbox state tree and includes it in the snapshot bundle +alongside the default `workspace/`. `snapshot restore` re-applies the full +per-agent set. No manual per-workspace backup pattern is needed. -The sandbox entrypoint ensures every per-agent workspace lives directly under the persistent `.openclaw/` tree, so state also survives `openshell sandbox restart`. +The sandbox entrypoint ensures every per-agent workspace lives directly under +the persistent `.openclaw/` tree, so state also survives `openshell sandbox restart`. ### Shared files across agents Files that operators typically want consistent across every per-agent workspace (`AGENTS.md`, shared skills, common templates) are **not** synced automatically. -Each workspace is independent, and changes in one do not propagate. -Operators that need this either copy the shared files explicitly to each workspace after editing or maintain a host-side sync layer. -NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). - - - - -## Hermes State - -Hermes does not use OpenClaw per-agent workspace directories. -NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable top-level files instead. -Refer to [Workspace Files](workspace-files.md) for the Hermes state layout. - - +Each workspace is independent; changes in one don't propagate. Operators that +need this either copy the shared files explicitly to each workspace after +editing, or maintain a host-side sync layer. Tracking shared-file tooling +(shared mount, `workspaces list` command) in +[#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). ## Next Steps -- [Workspace Files overview](workspace-files.md) to learn what each file does. +- [Workspace Files overview](workspace-files.md) to learn what each file does - Commands reference (use the `nemoclaw-user-reference` skill) diff --git a/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md b/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md deleted file mode 100644 index 4e3deaab2c..0000000000 --- a/skills/nemoclaw-user-manage-sandboxes/references/install-plugins-hermes.md +++ /dev/null @@ -1,117 +0,0 @@ -# Install Hermes Plugins - -Hermes plugins extend the Hermes runtime inside a NemoClaw-managed sandbox. -They are different from NemoClaw skills and from OpenClaw plugins, so install them through the Hermes plugin path instead of `skill install`. - -## How Hermes Loads Plugins - -NemoClaw sets `HERMES_HOME` to `/sandbox/.hermes` when it starts the Hermes gateway. -Hermes plugin directories live under `/sandbox/.hermes/plugins/`. -NemoClaw uses the same mechanism for its built-in Hermes integration, which the sandbox image bakes into `/sandbox/.hermes/plugins/nemoclaw`. - -The built-in NemoClaw Hermes plugin provides sandbox status tools, skill reload support, managed-tool broker patches, and runtime grounding for the OpenShell sandbox. -Do not replace or remove `/sandbox/.hermes/plugins/nemoclaw` when you add your own plugin. - -## Choose an Install Path - -Today, the supported path for custom Hermes plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. -Use this path when the plugin adds Python code, runtime hooks, or dependencies that Hermes must see at gateway startup. - -`nemohermes skill install ` is only for `SKILL.md` agent skills. -It uploads skill instructions and refreshes skill discovery, but it does not install Hermes runtime plugins. - -## Prepare a Build Directory - -Put the custom Dockerfile and everything it needs to `COPY` in one directory. -`nemohermes onboard --from ` sends the Dockerfile's parent directory as the Docker build context. -Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context. -NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them. - -```text -my-hermes-plugin-sandbox/ -├── Dockerfile -└── my-hermes-plugin/ - ├── __init__.py - └── requirements.txt -``` - -If you start from the stock NemoClaw Hermes Dockerfile, keep the NemoClaw Hermes image contract intact. -The image must still include the generated Hermes config, NemoClaw Hermes plugin, blueprint files, and `nemoclaw-start` entrypoint. - -**Warning:** - -A custom `--from` Dockerfile replaces the normal NemoClaw Hermes Dockerfile. - Starting from `ghcr.io/nvidia/nemoclaw/hermes-sandbox-base:latest` alone is not enough unless your Dockerfile also preserves the NemoClaw Hermes layers from `agents/hermes/Dockerfile`. - -## Install the Plugin in the Image - -Add your plugin after the Dockerfile has created `/sandbox/.hermes`. -The example below shows the layer that copies a plugin directory into the Hermes plugin tree. - -```dockerfile -COPY my-hermes-plugin/ /opt/my-hermes-plugin/ - -USER root -RUN mkdir -p /sandbox/.hermes/plugins/my-hermes-plugin \ - && cp -a /opt/my-hermes-plugin/. /sandbox/.hermes/plugins/my-hermes-plugin/ \ - && if [ -f /opt/my-hermes-plugin/requirements.txt ]; then \ - /opt/hermes/.venv/bin/python -m pip install --no-cache-dir -r /opt/my-hermes-plugin/requirements.txt; \ - fi \ - && chown -R sandbox:sandbox /sandbox/.hermes/plugins/my-hermes-plugin \ - && chmod -R a+rX /sandbox/.hermes/plugins/my-hermes-plugin - -USER sandbox -WORKDIR /sandbox -``` - -Keep plugin code and dependency files inside the build directory. -Avoid copying host credentials, local caches, or broad home-directory contents into the image. - -## Create the Sandbox - -Run onboarding with the custom Dockerfile and an explicit sandbox name. -NemoClaw requires a name for `--from` builds so a custom image cannot silently replace the default sandbox. - -```bash -nemohermes onboard --name my-hermes-build --from ./my-hermes-plugin-sandbox/Dockerfile -``` - -For non-interactive onboarding, set the same values through environment variables. - -```bash -NEMOCLAW_NON_INTERACTIVE=1 \ -NEMOCLAW_SANDBOX_NAME=my-hermes-build \ -NEMOCLAW_FROM_DOCKERFILE=./my-hermes-plugin-sandbox/Dockerfile \ -nemohermes onboard -``` - -If you resume an interrupted onboarding run, use the same Dockerfile path that started the session. -NemoClaw records the custom Dockerfile path and rejects a resume that points at a different image source. - -## Network Access - -Hermes plugins still run inside the OpenShell sandbox boundary. -If a plugin calls an external API at runtime, add a policy preset for the required hostnames and binaries before you recreate the sandbox. - -Hermes uses Python for plugin execution, so policy entries usually need to allow the Hermes Python runtime, such as `/opt/hermes/.venv/bin/python`, in addition to any command-line wrapper your plugin starts. -For package downloads during sandbox runtime, use the `pypi` preset or a custom preset that allows the package hosts you need. - -For policy concepts, refer to Network Policies (use the `nemoclaw-user-reference` skill). -For custom preset workflows, refer to Customize Network Policy (use the `nemoclaw-user-manage-policy` skill). - -## Common Mistakes - -These are the most common places where Hermes plugin installation gets mixed up with other NemoClaw extension paths. - -- Do not use `skill install` for Hermes runtime plugins. -- Do not install Hermes plugins into `/sandbox/.openclaw/extensions`; that path is for OpenClaw plugins. -- Do not remove `/sandbox/.hermes/plugins/nemoclaw`; NemoClaw depends on that plugin for managed Hermes behavior. -- Do not put the Dockerfile in a broad directory unless you intend to send that whole directory as the Docker build context. -- Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. -- Do not assume OpenShell policy allows Python package downloads during runtime by default. - -## Next Steps - -- Review NemoHermes Command Reference (use the `nemoclaw-user-reference` skill) for `nemohermes onboard --from` details. -- Review Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) if the plugin needs runtime network egress. -- Review [Runtime Controls](runtime-controls.md) before changing shields or mutability settings for a plugin-enabled sandbox. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md b/skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md new file mode 100644 index 0000000000..38d055b82f --- /dev/null +++ b/skills/nemoclaw-user-manage-sandboxes/references/lifecycle-details.md @@ -0,0 +1,26 @@ + + +# Manage Sandbox Lifecycle: Details + +## What Changes During a Rebuild + +Each rebuild destroys the existing container and creates a new one. +NemoClaw protects your data through the same backup-and-restore flow as `nemoclaw rebuild` (use the `nemoclaw-user-reference` skill): + +- NemoClaw preserves manifest-defined workspace state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the agent manifest, typically `/sandbox/.openclaw/workspace/`; for Hermes this also includes `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. +- NemoClaw does not preserve runtime changes outside the workspace state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-workspace paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. + +Aborts before the destroy step are non-destructive. +The flow refuses to proceed past preflight if a credential is missing or past backup if required manifest-defined state cannot be copied, so a failed run leaves the original sandbox intact and ready to retry. +When a backup command reports partial archive output, NemoClaw keeps the usable entries and reports only the manifest-defined paths that could not be archived. + +See [Backup and Restore](backup-restore.md) for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough. + +**If the rebuild aborts with `Missing credential: `:** + +The rebuild preflight reads the provider credential recorded by your last `nemoclaw onboard` session. +If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight may still reference the old key and fail before any destroy step runs. + +To recover, re-run `nemoclaw onboard` and select your current provider. +This refreshes the session metadata. +Your existing container keeps serving traffic until the new image is ready. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md b/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md index 978fd2fc2b..7bbedeb592 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md @@ -1,36 +1,24 @@ + + # Messaging Channels -import { AgentOnly } from "../_components/AgentGuide"; - Telegram, Discord, Slack, WeChat, and WhatsApp reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs. For token-based channels, NemoClaw registers credentials with OpenShell providers. WeChat captures a token through a host-side QR scan during onboarding. -WhatsApp pairs inside the sandbox through a QR scan and intentionally stores mutable session state there. +WhatsApp pairs inside the sandbox via QR scan and intentionally stores mutable session state there. NemoClaw bakes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control. **Experimental Channels:** WeChat and WhatsApp are experimental. Both rely on QR-based pairing flows that are more fragile than token-based bots, and the upstream client libraries can change behavior without notice. -Interfaces, defaults, and supported features can change, and NVIDIA does not recommend these channels for production use. +Interfaces, defaults, and supported features may change, and these channels are not recommended for production use. - -You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw channels` commands. -Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` at image build time, and changes inside the running container do not persist across rebuilds. - - You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw channels` commands. -Do not mutate messaging configuration directly inside the sandbox because NemoClaw generates `/sandbox/.hermes/.env` and Hermes config at image build time, and changes inside the running container do not persist across rebuilds. - +Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes at image build time, and changes inside the running container do not persist across rebuilds. - `nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) - - -`nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. -It only starts optional host services such as the cloudflared tunnel when that binary is present. - For details, refer to Commands (use the `nemoclaw-user-reference` skill). ## Prerequisites @@ -46,8 +34,8 @@ For details, refer to Commands (use the `nemoclaw-user-reference` skill). | Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | | Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` | | Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting, `SLACK_ALLOWED_CHANNELS` for channel ID allowlisting | -| WeChat (experimental) | None. Captured through host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | -| WhatsApp (experimental) | None. Pair through QR after rebuild | None | +| WeChat (experimental) | None. Captured via host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | +| WhatsApp (experimental) | None. Pair via QR after rebuild | None | Telegram uses a bot token from [BotFather](https://t.me/BotFather). Open Telegram, send `/newbot` to [@BotFather](https://t.me/BotFather), follow the prompts, and copy the token. @@ -68,25 +56,23 @@ Set `DISCORD_USER_ID` to restrict access to one user; otherwise, any member of t Slack uses Socket Mode and requires two tokens. Use `SLACK_BOT_TOKEN` for the bot user OAuth token (`xoxb-...`) and `SLACK_APP_TOKEN` for the app-level Socket Mode token (`xapp-...`). -NemoClaw validates both tokens before it saves Slack credentials or enables the channel. Set `SLACK_ALLOWED_USERS` to comma-separated Slack member IDs to authorize those users for DMs and for channel `@mention` events in channels where the Slack app is present. Set `SLACK_ALLOWED_CHANNELS` to comma-separated Slack channel IDs to restrict channel `@mention` handling to those channels. When both Slack allowlists are set, NemoClaw requires the mention to come from one of the allowed channels and one of the allowed members. Channel messages still require an explicit bot mention. -During sandbox startup, NemoClaw normalizes OpenShell credential placeholders into the environment shape expected by the Slack runtime, so post-rebuild Slack starts use the gateway-managed tokens instead of literal placeholder strings. -WeChat (experimental) delivers messages over Tencent's iLink gateway through the upstream `@tencent-weixin/openclaw-weixin` plugin baked into the sandbox base image and the built-in Hermes iLink WeChat adapter. +WeChat (experimental) delivers messages over Tencent's iLink gateway via the upstream `@tencent-weixin/openclaw-weixin` plugin baked into the sandbox base image and the built-in Hermes iLink WeChat adapter. The supported mode in this release is **personal WeChat** (`bot_type=3`). WeChat Official Account and WeCom/Enterprise WeChat are not wired up. Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemoclaw onboard`. You scan the QR with WeChat on your phone (Discover → Scan), confirm the login, and NemoClaw captures the token, `accountId`, `baseUrl`, and `userId` from the iLink response. NemoClaw registers the token as the `-wechat-bridge` OpenShell provider and substitutes the `openshell:resolve:env:WECHAT_BOT_TOKEN` placeholder for it inside the sandbox, so the token never lands in the image or on disk inside the running container. -NemoClaw bakes the non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake. +The non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) is baked into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake. WeChat is DM-only (`allowIdsMode: "dm"`). NemoClaw adds the operator who scanned the QR to `WECHAT_ALLOWED_IDS` automatically, and you can append more comma-separated WeChat user IDs through the same env var. -You can silence the host-side `[wechat]` diagnostic lines (poll status, IDC redirects, swallowed gateway errors) by exporting `NEMOCLAW_WECHAT_QUIET=1` after the flow is stable in your environment. +You can silence the host-side `[wechat]` diagnostic lines (poll status, IDC redirects, swallowed gateway errors) by exporting `NEMOCLAW_WECHAT_QUIET=1` once the flow is stable in your environment. Tencent's iLink gateway is a third-party service. Review your organization's terms-of-service, compliance, and data-residency constraints before enabling WeChat. @@ -94,17 +80,14 @@ Review your organization's terms-of-service, compliance, and data-residency cons WhatsApp (experimental) Web does not use a host-side token or OpenShell credential provider. NemoClaw advertises WhatsApp for both OpenClaw and Hermes sandboxes, and each agent completes pairing with its own in-sandbox command. Pairing happens inside the sandbox after the rebuild completes and creates mutable session credentials there. -Connect to the sandbox and then use the agent-specific pairing command to render the QR code in the terminal: +Run `openshell term` and then use the agent-specific pairing command to render the QR code in the terminal: -```bash -openclaw channels login --channel whatsapp # OpenClaw sandboxes -hermes whatsapp # Hermes sandboxes +```console +$ openclaw channels login --channel whatsapp # OpenClaw sandboxes +$ hermes whatsapp # Hermes sandboxes ``` -For OpenClaw sandboxes, NemoClaw validates the gateway URL before pairing and renders the WhatsApp QR code in a compact terminal form so it fits in smaller terminal windows. -If pairing exits with a gateway close such as `1008`, rerun the login command one time and then check `nemoclaw channels status --channel whatsapp` so you can diagnose the gateway/session path separately from QR rendering. - -The sandbox generates and stores session credentials inside durable agent state (`whatsapp` for OpenClaw, `platforms/whatsapp` for Hermes), so they survive rebuilds without re-pairing. +Session credentials are generated and stored inside durable agent state (`whatsapp` for OpenClaw, `platforms/whatsapp` for Hermes), so they survive rebuilds without re-pairing. This is the runtime tradeoff of enabling WhatsApp without a host bridge: a paired sandbox can use that WhatsApp account until you unpair it or clear the durable state. NemoClaw cannot detect cross-sandbox WhatsApp conflicts the way it does for token-based channels. Pair only one sandbox per WhatsApp account at a time. @@ -113,7 +96,6 @@ Pair only one sandbox per WhatsApp account at a time. When the wizard reaches **Messaging channels**, it lists Telegram, Discord, Slack, WeChat, and WhatsApp. Press a channel number to toggle it on or off, then press **Enter** when done. -If you select no channels, pressing **Enter** skips messaging setup. If a token-based channel token is not already in the environment or credential store, the wizard prompts for it and saves it. If you enable WeChat (experimental), the wizard does not prompt for a paste token. @@ -127,15 +109,15 @@ NemoClaw also selects the matching network policy preset during policy setup so For scripted setup, export the credentials and optional settings for the channels you want to enable before you run onboarding: -```bash -export TELEGRAM_BOT_TOKEN= -export TELEGRAM_REQUIRE_MENTION=1 -export DISCORD_BOT_TOKEN= -export DISCORD_SERVER_ID= -export SLACK_BOT_TOKEN= -export SLACK_APP_TOKEN= -export SLACK_ALLOWED_USERS= -export SLACK_ALLOWED_CHANNELS= +```console +$ export TELEGRAM_BOT_TOKEN= +$ export TELEGRAM_REQUIRE_MENTION=1 +$ export DISCORD_BOT_TOKEN= +$ export DISCORD_SERVER_ID= +$ export SLACK_BOT_TOKEN= +$ export SLACK_APP_TOKEN= +$ export SLACK_ALLOWED_USERS= +$ export SLACK_ALLOWED_CHANNELS= ``` This release does not support non-interactive WeChat configuration because the iLink QR handshake requires a human to scan the QR on a paired phone. @@ -143,8 +125,8 @@ Run `nemoclaw onboard` interactively when you want to enable WeChat. Then run onboarding: -```bash -nemoclaw onboard +```console +$ nemoclaw onboard ``` Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `-telegram-bridge` or `-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. @@ -154,56 +136,49 @@ Complete the rest of the wizard so the blueprint can create OpenShell providers Run channel commands from the host, not from inside the sandbox. Use `channels list` to see the supported channel names: -```bash -nemoclaw my-assistant channels list +```console +$ nemoclaw my-assistant channels list ``` Add the channel you want: -```bash -nemoclaw my-assistant channels add telegram -nemoclaw my-assistant channels add discord -nemoclaw my-assistant channels add slack -nemoclaw my-assistant channels add wechat -nemoclaw my-assistant channels add whatsapp +```console +$ nemoclaw my-assistant channels add telegram +$ nemoclaw my-assistant channels add discord +$ nemoclaw my-assistant channels add slack +$ nemoclaw my-assistant channels add wechat +$ nemoclaw my-assistant channels add whatsapp ``` `channels add` collects whatever each channel needs. It prompts for Telegram, Discord, and Slack tokens, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild. -It registers bridge providers with the OpenShell gateway when it captures tokens, records the channel in the sandbox registry, and asks whether to rebuild immediately. +It registers bridge providers with the OpenShell gateway when tokens were captured, records the channel in the sandbox registry, and asks whether to rebuild immediately. The command accepts mixed-case input such as `Telegram`, then stores and prints the canonical lowercase channel name. -`channels add` requires the matching built-in network policy preset YAML to be present. -A missing or malformed preset YAML (no `network_policies:` section) aborts the command before any token prompt, registry write, or rebuild prompt, so the sandbox never advertises a channel without a matching network policy. -With the preset file in place, `channels add` applies it to the sandbox before the rebuild so the bridge has egress to its upstream API. -When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean ` warning so the operator can clean up manually. -When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers. -It flags `gateway-providers` as residual because the in-flight upsert can leave the gateway with the new token. -Verify the gateway bridge before relying on the channel. -Restore the preset YAML and re-run `nemoclaw channels add `. +If a matching built-in network policy preset exists, `channels add` applies it to the sandbox automatically before the rebuild so the bridge has egress to its upstream API. +If applying the preset fails, NemoClaw warns and tells you to re-apply manually with `nemoclaw policy-add ` after the rebuild. Choose the rebuild so the running sandbox image picks up the new channel. -For Telegram, Discord, and Slack, `channels add` also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning. If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts. Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to test inbound agent replies, send a message from the Telegram client as an allowed user. For a repeatable live Telegram reply check, run `test/e2e/test-messaging-providers.sh` with `TELEGRAM_BOT_TOKEN_REAL`, `TELEGRAM_AUTHORIZED_CHAT_IDS` or `TELEGRAM_CHAT_ID`, and `NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E=1`. If you defer the rebuild, apply the change later: -```bash -nemoclaw my-assistant rebuild +```console +$ nemoclaw my-assistant rebuild ``` In non-interactive mode, set the required environment variables before running `channels add`. Missing credentials fail fast, and the command queues the change for a manual rebuild: -```bash -NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ +```console +$ NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ nemoclaw my-assistant channels add telegram -nemoclaw my-assistant rebuild +$ nemoclaw my-assistant rebuild ``` For Discord server access after onboarding, include the server settings when you add the channel and rebuild: -```bash -DISCORD_BOT_TOKEN= \ +```console +$ DISCORD_BOT_TOKEN= \ DISCORD_SERVER_ID= \ DISCORD_REQUIRE_MENTION=1 \ nemoclaw my-assistant channels add discord @@ -214,15 +189,15 @@ DISCORD_BOT_TOKEN= \ `channels add wechat` (experimental) follows the same shape as the other channels with two differences driven by the iLink QR handshake. First, the command does not prompt for a paste token. -Instead, it renders a QR code in your terminal, polls Tencent's iLink gateway, and captures both the bot token and the per-account metadata (`accountId`, `baseUrl`, `userId`) after you scan the QR with WeChat on your phone (**Discover** > **Scan**). +Instead, it renders a QR code in your terminal, polls Tencent's iLink gateway, and captures both the bot token and the per-account metadata (`accountId`, `baseUrl`, `userId`) once you scan the QR with WeChat on your phone (Discover → Scan). The login has an eight-minute deadline and refreshes the QR up to three times on expiry. Keep the terminal in the foreground until you see `✓ WeChat login confirmed`. Second, the command requires an interactive terminal. Non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`) fails fast with a clear error because the QR handshake needs a paired phone. -```bash -nemoclaw my-assistant channels add wechat +```console +$ nemoclaw my-assistant channels add wechat ``` If `WECHAT_BOT_TOKEN` is already cached for this sandbox (the operator onboarded with WeChat earlier), `channels add wechat` reuses the cached token and skips the QR scan to keep the upstream plugin's existing iLink session intact. @@ -238,9 +213,9 @@ Rebuild the sandbox after the update so the image reflects the current channel s To remove a channel and clear its stored credentials, run: -```bash -nemoclaw my-assistant channels remove telegram -nemoclaw my-assistant channels remove wechat +```console +$ nemoclaw my-assistant channels remove telegram +$ nemoclaw my-assistant channels remove wechat ``` `channels remove wechat` clears the bot token, deletes the `-wechat-bridge` OpenShell provider, and drops `wechat` from the sandbox's enabled-channel set. @@ -252,27 +227,21 @@ The cleanup tries `openshell sandbox exec` and falls back to SSH if that does no If neither transport can reach a running sandbox for a QR-paired channel, the command exits non-zero and asks you to start the sandbox and re-run. NemoClaw deliberately leaves the registry, policy preset, and `session.policyPresets` unchanged on that failure path, so a follow-up re-run completes the removal cleanly. -`channels remove whatsapp` clears the client-side Baileys session inside the sandbox. -It cannot deregister the linked device with WhatsApp's servers because that requires an active Baileys connection to issue the logout RPC, and the command no longer has that connection after it removes the session files. +`channels remove whatsapp` clears the client-side Baileys session inside the sandbox; it cannot deregister the linked device with WhatsApp's servers because that requires an active Baileys connection to issue the logout RPC, which we no longer have once the session files are gone. The phone account will continue to list the sandbox as a Linked Device until you remove it manually from your phone (Settings → Linked Devices → tap the entry → Log out) or until WhatsApp's 14-day inactivity timeout expires. -Remove the entry from the phone if you plan to re-pair the same phone with a different sandbox. +Removing the entry from the phone is recommended if you plan to re-pair the same phone with a different sandbox. Use `channels stop` when you want to pause a bridge without deleting credentials: -```bash -nemoclaw my-assistant channels stop telegram -nemoclaw my-assistant channels start telegram +```console +$ nemoclaw my-assistant channels stop telegram +$ nemoclaw my-assistant channels start telegram -nemoclaw my-assistant channels stop wechat -nemoclaw my-assistant channels start wechat +$ nemoclaw my-assistant channels stop wechat +$ nemoclaw my-assistant channels start wechat ``` - For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.openclaw/openclaw-weixin/accounts/` intact even though the bridge is no longer wired up in `openclaw.json`. - - -For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.hermes/` intact even though the bridge is no longer wired up in Hermes config. - A subsequent `channels start wechat` plus rebuild revives the bridge against the same iLink account without a fresh QR scan. The bot token is held by the OpenShell provider across the stop/start cycle. @@ -289,12 +258,7 @@ Re-run `channels add ` with the intended token to refresh the stored no ## Stop Messaging Delivery Use `channels stop` when you want to pause one bridge and keep the sandbox running. - Use `nemoclaw tunnel stop` or its deprecated alias `nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox. - - -Use `nemoclaw tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox. - Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway. ## Confirm Delivery @@ -305,29 +269,17 @@ Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `wh ## Tunnel Command - When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL. - - -When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. - Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL. - `nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. The older `nemoclaw start` still works as a deprecated alias. - - -`nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. - -```bash -nemoclaw tunnel start +```console +$ nemoclaw tunnel start ``` ## Related Topics - - Deploy NemoClaw to a Remote GPU Instance (use the `nemoclaw-user-deploy-remote` skill) for remote deployment with messaging. - - Architecture (use the `nemoclaw-user-reference` skill) for how providers, the gateway, and the sandbox fit together. - Commands (use the `nemoclaw-user-reference` skill) for `channels add`, `channels remove`, `channels start`, `channels stop`, `tunnel start`, `tunnel stop`, and `status`. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md b/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md index e5e026974b..9450277507 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/runtime-controls.md @@ -1,82 +1,41 @@ + + # Runtime Controls and Sandbox Mutability -import { AgentOnly } from "../_components/AgentGuide"; - This page explains which parts of a running NemoClaw sandbox can change immediately and which changes require a rebuild or re-onboard. -## What You Can Change at Runtime +## What you can change at runtime -NemoClaw applies its security posture in three layers: what onboarding bakes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard. +NemoClaw applies its security posture in three layers — what is baked into the sandbox image at onboard, what is hot-reloadable on the running sandbox, and what requires a rebuild or re-onboard. The table below maps each commonly changed item to the layer that owns it and the command that changes it. - - | Item | When the change takes effect | How to change it | |---|---|---| -| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw rebuild` after picking a different provider with `nemoclaw inference set` | +| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw rebuild` after picking a different provider via `nemoclaw inference set` | | Inference model on the current provider | Rebuild required for OpenClaw; hot-reloadable for managed routers | `nemoclaw rebuild` (OpenClaw) or `nemoclaw inference set` (router-based) | | Sub-agent (Hermes / OpenClaw / …) | Re-onboard required (the sub-agent and its workspace are baked at onboard) | `nemoclaw onboard --recreate-sandbox` | -| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | -| Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | +| Network policy preset (slack, discord, telegram, brave, …) | Runtime — applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | +| Network allow-list (custom hosts) | Runtime — picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | | Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw channels add ` then accept the rebuild prompt | | Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, see #3453) | `nemoclaw channels stop ` then rebuild | -| Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | -| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | -| Default OpenClaw workspace template seed (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`) | Locked at first sandbox boot. Re-onboard required to change the bake-time choice. | Set `NEMOCLAW_MINIMAL_BOOTSTRAP=1` before `nemoclaw onboard` to skip default template seeding for new/pristine workspaces. **Does not delete files already present.** Partial mitigation for #2598 (cuts ~3k tokens of project-context overhead off OpenClaw's per-turn bootstrap injection). | -| Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | +| Dashboard forward port | Runtime — port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= nemoclaw connect` | +| Dashboard bind address (loopback vs all interfaces) | Runtime — applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 nemoclaw connect` (see #3259) | +| Web search backend (Brave, Tavily, etc.) | Runtime via `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `nemoclaw config set --key web.backend --value tavily` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation** — no runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | | Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | | GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | -| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime. OpenClaw hot-reloads on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned | -| `openclaw.json` keys (general: model, agents.list, web.backend, channel config, and so on) | Mixed. Individual keys still follow the rebuild rules in the rows above, such as provider switch requiring rebuild even after editing the JSON. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | +| Agents allow-list (`agents.list` in `openclaw.json`) | Runtime — hot-reloaded by OpenClaw on config change | Prefer agent or NemoClaw commands that keep host and sandbox state aligned | +| `openclaw.json` keys (general — model, agents.list, web.backend, channel config, etc.) | Mixed. Individual keys still follow the rebuild rules in the rows above, such as provider switch requiring rebuild even after editing the JSON. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | If a row above conflicts with what you observe, the runtime source of truth inside the sandbox is `/opt/nemoclaw/openclaw.json`; the host registry caches metadata but the image and OpenClaw read from the in-sandbox file. - - - -| Item | When the change takes effect | How to change it | -|---|---|---| -| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `nemoclaw inference set` for route changes, or `nemoclaw rebuild` after changing build-time settings | -| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemoclaw inference set` | -| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemoclaw onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` | -| Network policy preset (slack, discord, telegram, brave, …) | Runtime. Applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemoclaw policy-add ` / `policy-remove ` | -| Network allow-list (custom hosts) | Runtime. Picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | -| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemoclaw channels add ` then accept the rebuild prompt | -| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`/sandbox/.hermes/.env` and Hermes config are baked at image build time) | `nemoclaw channels stop ` then rebuild | -| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemoclaw connect` or `openshell forward start` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemoclaw onboard --recreate-sandbox` | -| Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | -| GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | -| Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `nemoclaw inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | - -If a row above conflicts with what you observe, the runtime source of truth for -Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`; the host -registry caches metadata but the image and Hermes runtime read from the -in-sandbox files. - - - -## See Also +## See also The mutability table above is a consolidated index of information that lives in more detail on per-topic pages: - - -- [Manage Sandbox Lifecycle](../SKILL.md) for the full rebuild, re-onboard, and upgrade workflow. -- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for the rebuild path for provider and model changes. -- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) for runtime policy editing and operator approval flow. -- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the per-attack-surface posture table that this page complements. -- OpenClaw Security Controls (use the `nemoclaw-user-configure-security` skill) for application-layer controls that operate independently of NemoClaw. -- CLI Commands Reference (use the `nemoclaw-user-reference` skill) for the full flag surface for every `nemoclaw` command, including the environment variables that affect runtime behavior. - - - - -- [Manage Sandbox Lifecycle](../SKILL.md) for the full rebuild, re-onboard, and upgrade workflow. -- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) for the runtime route and rebuild paths for provider and model changes. -- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) for runtime policy editing and operator approval flow. -- Security Best Practices (use the `nemoclaw-user-configure-security` skill) for the per-attack-surface posture table that this page complements. -- CLI Commands Reference (use the `nemoclaw-user-reference` skill) for the full flag surface for every `nemoclaw` and `nemoclaw` command, including the environment variables that affect runtime behavior. - - +- [Manage Sandbox Lifecycle](../SKILL.md) — full rebuild / re-onboard / upgrade workflow. +- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) — the rebuild path for provider and model changes. +- Customize Network Policy (use the `nemoclaw-user-manage-policy` skill) and Approve Network Requests (use the `nemoclaw-user-manage-policy` skill) — runtime policy editing and operator approval flow. +- Security Best Practices (use the `nemoclaw-user-configure-security` skill) — the per-attack-surface posture table that this page complements. +- OpenClaw Security Controls (use the `nemoclaw-user-configure-security` skill) — application-layer controls that operate independently of NemoClaw. +- CLI Commands Reference (use the `nemoclaw-user-reference` skill) — full flag surface for every `nemoclaw` command, including the env vars that affect runtime behavior. diff --git a/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md b/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md index a6d1a13b62..b8b0731df8 100644 --- a/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md +++ b/skills/nemoclaw-user-manage-sandboxes/references/workspace-files.md @@ -1,9 +1,7 @@ + + # Workspace Files -import { AgentOnly } from "../_components/AgentGuide"; - - - OpenClaw stores its personality, user context, and behavioral configuration in a set of Markdown files inside the sandbox. These files live at `/sandbox/.openclaw/workspace/` and are collectively called **workspace files**. @@ -13,7 +11,7 @@ These files live at `/sandbox/.openclaw/workspace/` and are collectively called |---|---| | `SOUL.md` | Defines the agent's persona, tone, and communication style. | | `USER.md` | Stores information about the human the agent assists. | -| `IDENTITY.md` | Short identity card with name, language, emoji, and creature type. | +| `IDENTITY.md` | Short identity card — name, language, emoji, creature type. | | `AGENTS.md` | Behavioral rules, memory conventions, safety guidelines, and session workflow. | | `MEMORY.md` | Curated long-term memory distilled from daily notes. | | `memory/` | Directory of daily note files (`YYYY-MM-DD.md`) for session continuity. | @@ -37,7 +35,7 @@ All workspace files reside inside the sandbox filesystem: ## Multi-Agent Deployments A single NemoClaw sandbox can host more than one OpenClaw agent. -When you configure OpenClaw with multiple named agents (for example, a shared `main` agent +When OpenClaw is configured with multiple named agents (e.g., a shared `main` agent plus per-user agents for a Teams-integrated deployment), each agent gets its own workspace directory alongside the default `workspace/`: @@ -51,23 +49,27 @@ workspace directory alongside the default `workspace/`: Each per-agent workspace contains the same Markdown file structure as the default (`SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `MEMORY.md`, `memory/`). -Files are per-agent. Changes in `workspace-main/AGENTS.md` are not visible to +Files are per-agent — changes in `workspace-main/AGENTS.md` are not visible to `workspace-support/`. -NemoClaw handles persistence and snapshots automatically for per-agent workspaces: -the sandbox entrypoint provisions each `workspace-/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `nemoclaw snapshot create` discovers every `workspace-/` directory and includes it in the snapshot bundle alongside the default `workspace/`. +Persistence and snapshots are handled automatically for per-agent workspaces: +the sandbox entrypoint provisions each `workspace-/` directly under the +writable `.openclaw/` tree so state survives sandbox restart, and +`nemoclaw snapshot create` discovers every `workspace-/` directory +and includes it in the snapshot bundle alongside the default `workspace/`. **Note:** Files that operators typically want consistent across every agent workspace (`AGENTS.md`, shared skills, common templates) are not synced automatically. -Each workspace is independent, and changes in one do not propagate. -NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). +Each workspace is independent; changes in one don't propagate. Tracking +shared-file tooling (shared mount, `workspaces list` command) in +[#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). ## Persistence Behavior Workspace files live in the sandbox's persistent state volume, not in the container image. -They survive normal container restarts, but NemoClaw deletes them when you destroy the sandbox. +This means they survive normal container restarts, but they are deleted when you destroy the sandbox. ### Preserved During Restart, Rebuild, and Upgrade @@ -81,7 +83,7 @@ It does not continue with a partial backup. ### Deleted During Sandbox Destroy Running `nemoclaw destroy` deletes the sandbox and its persistent state volume. -NemoClaw removes workspace files from the sandbox unless you created a snapshot or backup first. +Workspace files are removed from the sandbox unless you created a snapshot or backup first. **Warning:** @@ -101,26 +103,3 @@ You can edit them in two ways: - Set Up Task-Specific Sub-Agents (use the `nemoclaw-user-configure-inference` skill) - [Backup and Restore workspace files](backup-restore.md) - Commands reference (use the `nemoclaw-user-reference` skill) - - - - -Hermes stores durable agent state under `/sandbox/.hermes/` instead of the OpenClaw workspace directory. -The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environment settings live in `/sandbox/.hermes/.env`, and runtime state such as logs, memory, platform sessions, and the SQLite state database lives under the same `.hermes` tree. - -## Important Hermes State - -| Path | Purpose | -|---|---| -| `/sandbox/.hermes/config.yaml` | NemoClaw-generated Hermes runtime configuration. | -| `/sandbox/.hermes/.env` | NemoClaw-generated environment and messaging placeholders. | -| `/sandbox/.hermes/state.db` | Hermes SQLite state database. | -| `/sandbox/.hermes/platforms/` | Messaging platform state, including QR-paired sessions such as WhatsApp. | -| `/sandbox/.hermes/logs/` | Hermes runtime logs. | -| `/sandbox/SOUL.md` | Durable top-level Hermes persona file preserved by NemoClaw snapshots. | - -## Editing State - -Prefer NemoClaw host commands for generated configuration such as model, provider, messaging, and policy settings. -Direct edits to `/sandbox/.hermes/config.yaml` or `/sandbox/.hermes/.env` can be overwritten by rebuilds. -Use `nemoclaw connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. diff --git a/skills/nemoclaw-user-monitor-sandbox/SKILL.md b/skills/nemoclaw-user-monitor-sandbox/SKILL.md index 1915fb8619..80192e7c14 100644 --- a/skills/nemoclaw-user-monitor-sandbox/SKILL.md +++ b/skills/nemoclaw-user-monitor-sandbox/SKILL.md @@ -4,6 +4,9 @@ description: "Inspects sandbox health, traces agent behavior, and diagnoses prob license: "Apache-2.0" --- + + + # Monitor Sandbox Activity and Debug Issues ## Prerequisites @@ -11,27 +14,25 @@ license: "Apache-2.0" - A running NemoClaw sandbox. - The OpenShell CLI on your `PATH`. -import { AgentOnly } from "../_components/AgentGuide"; - Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems. ## Check Sandbox Health Run the status command to view the sandbox state, gateway health, and active inference configuration: -```bash -nemoclaw status +```console +$ nemoclaw status ``` For local Ollama and local vLLM routes, `nemoclaw status` also probes the host-side health endpoint directly. -This check catches a stopped local backend before you retry `inference.local` from inside the sandbox. +This catches a stopped local backend before you retry `inference.local` from inside the sandbox. -Key output fields include: +Key fields in the output include the following: -- Sandbox details show the configured model, provider, GPU mode, and applied policy presets. -- Gateway and process health show whether NemoClaw can still reach the OpenShell gateway and whether the in-sandbox agent process is running. -- Inference health for local Ollama and local vLLM shows `healthy` or `unreachable` together with the probed local URL. -- NIM status shows whether a NIM container is running and healthy when that path is in use. +- Sandbox details, which show the configured model, provider, GPU mode, and applied policy presets. +- Gateway and process health, which show whether NemoClaw can still reach the OpenShell gateway and whether the in-sandbox agent process is running. +- Inference health for local Ollama and local vLLM, which shows `healthy` or `unreachable` together with the probed local URL. +- NIM status, which shows whether a NIM container is running and healthy when that path is in use. Run `nemoclaw status` on the host to check sandbox state. Use `openshell sandbox list` for the underlying sandbox details. @@ -40,51 +41,22 @@ Use `openshell sandbox list` for the underlying sandbox details. Stream the most recent log output from the blueprint runner and sandbox: -```bash -nemoclaw logs -``` - -To follow the log output in real time: - -```bash -nemoclaw logs --follow -``` - -The `logs` command shows lifecycle and gateway output. -It does not export the structured per-session agent state that OpenClaw stores under `.openclaw/agents/`. - -## Inspect Agent Session State - -OpenClaw stores structured session state inside the sandbox. -Use these files when you need an audit trail, a compliance review surface, or replay tooling that includes assistant messages and tool activity. - -| File | Purpose | -|---|---| -| `/sandbox/.openclaw/agents/main/sessions/.jsonl` | Per-session event log. Use this file for audit trails and compliance dashboards. Records can include assistant messages, `thinking` blocks, tool calls, tool results, token usage, and cost metadata. | -| `/sandbox/.openclaw/agents/main/sessions/.trajectory.jsonl` | Lower-level trajectory data for fine-grained replay. This file can be large, so avoid using it for routine audit summaries. | -| `/sandbox/.openclaw/agents/main/sessions/sessions.json` | Session index that maps known session keys to their persisted state. | - -To inspect the session directory from the host, run a sandbox command: - ```console -$ nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions +$ nemoclaw logs ``` -To copy a session log for offline review, use the OpenShell sandbox download command: +To follow the log output in real time: ```console -$ openshell sandbox download /sandbox/.openclaw/agents/main/sessions/.jsonl . +$ nemoclaw logs --follow ``` -Treat exported session logs as sensitive data. -They can contain prompts, tool inputs, tool outputs, file paths, and cost metadata from the agent run. - ## Monitor Network Activity in the TUI Open the OpenShell terminal UI for a live view of sandbox network activity and egress requests: -```bash -openshell term +```console +$ openshell term ``` For a remote sandbox, SSH to the instance and run `openshell term` there. @@ -101,18 +73,10 @@ Refer to Approve or Deny Agent Network Requests (use the `nemoclaw-user-manage-p Run a test inference request to verify that the provider is responding: - -```bash -nemoclaw my-assistant connect -openclaw agent --agent main -m "Test inference" --session-id debug -``` - - -```bash -nemoclaw my-hermes connect -hermes +```console +$ nemoclaw my-assistant connect +$ openclaw agent --agent main -m "Test inference" --session-id debug ``` - If the request fails, check the following: diff --git a/skills/nemoclaw-user-overview/SKILL.md b/skills/nemoclaw-user-overview/SKILL.md index 89f0056373..41250f65ec 100644 --- a/skills/nemoclaw-user-overview/SKILL.md +++ b/skills/nemoclaw-user-overview/SKILL.md @@ -1,15 +1,17 @@ --- name: "nemoclaw-user-overview" -description: "Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Trigger keywords - nemoclaw overview, openclaw always-on assistants, hermes agent, nvidia openshell, nvidia nemotron, nemoclaw ecosystem, nemohermes, nemoclaw vs openshell, run hermes openshell sandbox, openclaw openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw release notes, nemoclaw changelog." +description: "Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Trigger keywords - nemoclaw ecosystem, openclaw openshell, nemoclaw vs openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw overview, openclaw always-on assistants, nvidia openshell, nvidia nemotron, nemoclaw release notes, nemoclaw changelog." license: "Apache-2.0" --- -# NemoClaw User Overview + + + +# Ecosystem ## References -- **Load [references/overview.md](references/overview.md)** when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. -- **Load [references/ecosystem-hermes.md](references/ecosystem-hermes.md)** when users ask about Hermes, OpenShell, and NemoClaw together, or when to use NemoClaw versus OpenShell for Hermes. Explains how Hermes, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond integrating OpenShell yourself, and when to prefer NemoHermes versus OpenShell. - **Load [references/ecosystem.md](references/ecosystem.md)** when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. - **Load [references/how-it-works.md](references/how-it-works.md)** for sandbox lifecycle and architecture mechanics; not for product definition (Overview) or multi-project placement (Ecosystem). Describes how NemoClaw works internally: CLI, plugin, blueprint runner, OpenShell orchestration, inference routing, and protection layers. +- **Load [references/overview.md](references/overview.md)** when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works. Explains what NemoClaw covers: onboarding, lifecycle management, and OpenClaw operations within OpenShell containers, plus capabilities and why it exists. - **Load [references/release-notes.md](references/release-notes.md)** when users ask about recent changes, the release cadence, or where to track versioned assets on GitHub. Includes the NemoClaw release notes. diff --git a/skills/nemoclaw-user-overview/references/ecosystem-hermes.md b/skills/nemoclaw-user-overview/references/ecosystem-hermes.md deleted file mode 100644 index ae660f0ad6..0000000000 --- a/skills/nemoclaw-user-overview/references/ecosystem-hermes.md +++ /dev/null @@ -1,93 +0,0 @@ -# Ecosystem - -NemoClaw provides onboarding, lifecycle management, and Hermes operations within OpenShell containers. -Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected. - -This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and how to choose between NemoHermes and OpenShell alone. - -## How the Stack Fits Together - -A NemoClaw for Hermes deployment combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw. -The following diagram shows how they fit together. - -```mermaid -flowchart TB - NC["🦞 NVIDIA NemoClaw
CLI, blueprint"] - OS["🐚 NVIDIA OpenShell
Gateway, policy, inference routing"] - HM["Hermes
Agent in sandbox"] - - NC -->|orchestrates| OS - OS -->|isolates and runs| HM - - classDef nv fill:#76b900,stroke:#333,color:#fff - classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a - classDef nvDark fill:#333,stroke:#76b900,color:#fff - - class NC nv - class OS nv - class HM nvDark - - linkStyle 0 stroke:#76b900,stroke-width:2px - linkStyle 1 stroke:#76b900,stroke-width:2px -``` - -NemoClaw sits above OpenShell in the operator workflow. -It drives OpenShell APIs and CLI to create and configure the sandbox that runs Hermes. -Models and endpoints sit behind OpenShell's inference routing. -NemoClaw onboarding wires provider choice into that routing, including the Hermes Provider route when you onboard through `nemohermes`. - -The following table shows the scope of each component in the stack. - -| Project | Scope | -|---------|--------| -| [Hermes](https://hermes-agent.nousresearch.com/docs/) | The agent: runtime, tools, messaging adapters, and an OpenAI-compatible API inside the container. It does not define the sandbox or the host gateway. | -| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | -| NemoClaw | The NVIDIA reference stack on the host: `nemohermes` / `nemoclaw` CLI, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so Hermes runs inside OpenShell in a documented, repeatable way. | - -## NemoClaw Path versus OpenShell Path - -Both paths assume OpenShell can sandbox a workload. -The difference is who owns the integration work. - -| Path | What it means | -|------|---------------| -| **NemoClaw path** | You adopt the reference stack. NemoClaw's Hermes blueprint encodes a hardened image, default policies, and orchestration so `nemohermes onboard` can create a known-good Hermes-on-OpenShell setup with less custom glue. | -| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | - -## What NemoClaw Adds Beyond Custom OpenShell - -You can run Hermes inside OpenShell without NemoClaw by building your own image, writing policy YAML, registering providers, and wiring inference routes yourself. -That path is valid when you need full control over the container layout. - -NemoClaw builds on OpenShell with additional security hardening, automation, and lifecycle tooling for Hermes. -The following table compares custom OpenShell integration with `nemohermes onboard`. - -| Capability | Custom OpenShell + Hermes | `nemohermes onboard` | -|---|---|---| -| Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. | -| Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. | -| Image hardening | Depends on your base image and install steps. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | -| Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. | -| Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates credentials from the host, configures the OpenShell route, and bakes model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. | -| Channel messaging | OpenShell delivers channel tokens through its provider system and L7 proxy; you configure Hermes platform adapters manually. | NemoClaw automates supported channel setup during onboarding and bakes Hermes env/config with placeholder tokens that OpenShell resolves at egress. | -| Blueprint versioning | No NemoClaw blueprint; your image tag is whatever you built locally. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemohermes onboard` on different machines produces the same sandbox. | -| State migration | Not included unless you build it. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. | -| Process count limits | You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint on top of OpenShell's seccomp and privilege dropping. | - -## When to Use Which - -Use the following table to decide when to use NemoHermes versus OpenShell alone. - -| Situation | Prefer | -|-----------|--------| -| You want Hermes with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw (`nemohermes`) | -| You need maximum flexibility for custom images, a layout that does not match the NemoClaw Hermes blueprint, or a workload outside this reference stack. | OpenShell with your own integration | -| You are standardizing on the NVIDIA reference for always-on Hermes agents with policy and inference routing. | NemoClaw (`nemohermes`) | -| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | - -## Related Topics - -- [Overview](overview.md) describes what NemoClaw is, including capabilities, benefits, and use cases. -- [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. diff --git a/skills/nemoclaw-user-overview/references/ecosystem.md b/skills/nemoclaw-user-overview/references/ecosystem.md index a5a11e289c..b1d97c4a22 100644 --- a/skills/nemoclaw-user-overview/references/ecosystem.md +++ b/skills/nemoclaw-user-overview/references/ecosystem.md @@ -1,12 +1,14 @@ + + # Ecosystem NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. -This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. +This page describes how the ecosystem is formed across projects, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. ## How the Stack Fits Together -A NemoClaw for OpenClaw deployment combines three pieces with distinct scopes: OpenClaw, OpenShell, and NemoClaw. +There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope. The following diagram shows how they fit together. ```mermaid @@ -50,7 +52,7 @@ The difference is who owns the integration work. | Path | What it means | |------|---------------| -| **NemoClaw path** | You adopt the reference stack. NemoClaw's blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can create a known-good OpenClaw-on-OpenShell setup with less custom glue. | +| **NemoClaw path** | You adopt the reference stack. NemoClaw's blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can stand up a known-good OpenClaw-on-OpenShell setup with less custom glue. | | **OpenShell path** | You use OpenShell as the platform and supply your own container, install steps for OpenClaw, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond the OpenShell Community Sandbox @@ -68,7 +70,7 @@ The following table compares the two paths. | Credential handling | OpenShell's provider system replaces real credentials with placeholder tokens in the sandbox environment. The L7 proxy resolves placeholders to real values at egress. You create providers manually with `openshell provider create`. | NemoClaw creates OpenShell providers automatically during onboarding. It also filters sensitive host environment variables (provider API keys, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`) from the sandbox creation command to prevent accidental leakage through build args. | | Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | | Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths natively. | -| Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host, and OpenShell's provider system delivers them. | +| Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw's onboarding wizard validates your credential from the host, lets you select a provider (NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, Ollama, and compatible endpoints), and configures OpenShell's inference routing automatically. Credentials stay on the host and are delivered through OpenShell's provider system. | | Channel messaging | OpenShell provides the credential provider system and L7 proxy that delivers channel tokens securely (including path-based resolution for Telegram's `/bot/` URL pattern). You create providers and configure OpenClaw's channel settings manually. | NemoClaw automates channel setup during onboarding: it collects bot tokens, registers them as OpenShell providers, and bakes OpenClaw channel config with placeholder tokens that OpenShell's proxy resolves at egress. No separate bridge process runs on the host. | | Blueprint versioning | No blueprint. The community sandbox uses whatever image version is currently published. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemoclaw onboard` on different machines produces the same sandbox. | | State migration | Not included. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. | @@ -85,8 +87,8 @@ Use the following table to decide when to use NemoClaw versus OpenShell. | You are standardizing on the NVIDIA reference for always-on assistants with policy and inference routing. | NemoClaw | | You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | -## Related Topics +## Related topics -- [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. +- [Overview](overview.md) contains what NemoClaw is, capabilities, benefits, and use cases. +- [How It Works](how-it-works.md) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers. - Architecture (use the `nemoclaw-user-reference` skill) shows the repository structure and technical diagrams. diff --git a/skills/nemoclaw-user-overview/references/how-it-works.md b/skills/nemoclaw-user-overview/references/how-it-works.md index fd7a9108a5..b0f9f4a240 100644 --- a/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/skills/nemoclaw-user-overview/references/how-it-works.md @@ -1,17 +1,11 @@ + + # NemoClaw Architecture Overview -import { AgentCli, AgentOnly } from "../_components/AgentGuide"; +This page explains how NemoClaw runs OpenClaw inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. -This page explains how NemoClaw runs supported agents inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. - -NemoClaw does not replace OpenShell or your chosen agent runtime. -It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, and state helpers. - -OpenClaw sandboxes also load the NemoClaw plugin for managed inference metadata and the `/nemoclaw` slash command. - - -Hermes sandboxes receive agent configuration under `/sandbox/.hermes` during onboarding instead of the OpenClaw plugin path. - +NemoClaw does not replace OpenClaw or OpenShell. +It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, plugin configuration, and state helpers. You can use that setup directly or adapt it for your own OpenShell integration. ## High-Level Flow @@ -29,7 +23,7 @@ The diagram has the following components: | Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. | | NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. | | OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. | -| NemoClaw sandbox | Runs the onboarded agent with the selected blueprint contents and supporting tools. | +| NemoClaw sandbox | Runs OpenClaw with the NemoClaw plugin, the selected blueprint contents, and supporting tools. | | Inference | Receives model requests through the gateway, using NVIDIA endpoints, NIM, or compatible APIs. | | Integrations | Reach messaging services, MCP servers, GitHub, package indexes, or model hubs through gateway-managed egress. | | State and artifacts | Store configuration, credentials, logs, workspace files, policies, and transcripts outside the running agent process. | @@ -38,49 +32,39 @@ For repository layout, file paths, and deeper diagrams, see Architecture (use th ## Design Principles -NemoClaw follows these architecture principles. +NemoClaw architecture follows the following principles. -Versioned blueprint -: Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. - The OpenClaw sandbox plugin stays small and stable inside the container. +Thin plugin, versioned blueprint +: The sandbox plugin stays small and stable. Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. Respect CLI boundaries -: The CLI is the primary interface for sandbox management. +: The `nemoclaw` CLI is the primary interface for sandbox management. Supply chain safety : Blueprint artifacts are immutable, versioned, and digest-verified before execution. OpenShell-backed lifecycle -: NemoClaw orchestrates OpenShell resources under the hood, but onboard is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes. +: NemoClaw orchestrates OpenShell resources under the hood, but `nemoclaw onboard` + is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes. Reproducible setup : Running setup again recreates the sandbox from the same blueprint and policy definitions. ## CLI, Plugin, and Blueprint -NemoClaw is split into integration pieces on the host and in the sandbox image: +NemoClaw is split into three integration pieces: - The _host CLI_ runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations. - - - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. - Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. - - - - -- NemoClaw writes Hermes runtime configuration into `/sandbox/.hermes` during onboarding, including `config.yaml`, environment files, and platform adapter settings for supported messaging channels. - - - The _blueprint_ is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell. -This separation keeps agent-specific sandbox assets focused while allowing host orchestration and blueprint contents to evolve on their own release cadence. +This separation keeps the sandbox plugin small while allowing host orchestration and blueprint contents to evolve on their own release cadence. ## Sandbox Creation -When you run onboard, NemoClaw creates an OpenShell sandbox that runs your selected agent in an isolated container. +When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container. The host CLI and blueprint runner orchestrate this process through the OpenShell CLI: 1. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest. @@ -96,9 +80,6 @@ OpenShell intercepts every inference call and routes it to the configured provid During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell route, and bakes the matching model reference into the sandbox image. The sandbox then talks to `inference.local`, while the host owns the actual provider credential and upstream endpoint. If you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. - -For Hermes, runtime model switches through inference set update `/sandbox/.hermes/config.yaml` without rebuilding the sandbox. - ## Protection Layers @@ -112,26 +93,12 @@ The sandbox starts with a default policy that controls network egress, filesyste | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. -NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. - -## Next Steps - +For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill). For container-level hardening, refer to Sandbox Hardening (use the `nemoclaw-user-deploy-remote` skill). -- Read [Ecosystem](ecosystem.md) for stack-level relationships and NemoClaw versus OpenShell-only paths. -- Follow Quickstart with OpenClaw (use the `nemoclaw-user-get-started` skill) to launch your first sandbox. -- Refer to the Architecture (use the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle. -- Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for detailed provider configuration. -- For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill). -- For container-level hardening, refer to Sandbox Hardening. - - - +## Next Steps - Read [Ecosystem](ecosystem.md) for stack-level relationships and NemoClaw versus OpenShell-only paths. -- Follow Quickstart with Hermes (use the `nemoclaw-user-get-started` skill) to launch your first sandbox. +- Follow the Quickstart (use the `nemoclaw-user-get-started` skill) to launch your first sandbox. - Refer to the Architecture (use the `nemoclaw-user-reference` skill) for the full technical structure, including file layouts and the blueprint lifecycle. - Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill) for detailed provider configuration. -- For details on the baseline rules, refer to Network Policies (use the `nemoclaw-user-reference` skill). - - diff --git a/skills/nemoclaw-user-overview/references/overview.md b/skills/nemoclaw-user-overview/references/overview.md index a5dc5d525f..ca25355fb5 100644 --- a/skills/nemoclaw-user-overview/references/overview.md +++ b/skills/nemoclaw-user-overview/references/overview.md @@ -1,19 +1,18 @@ + + # Overview of NVIDIA NemoClaw -import { AgentCli, AgentOnly } from "../_components/AgentGuide"; - -NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside OpenShell containers. -NemoClaw provides onboarding, lifecycle management, and agent operations for supported runtimes in OpenShell sandboxes. -It incorporates policy-based privacy and security guardrails, giving you control over your agents' behavior and data handling. -These controls help self-evolving agents run more safely in clouds, on-premises environments, RTX PCs, and DGX Spark. +NVIDIA NemoClaw is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants more safely. +NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. +It incorporates policy-based privacy and security guardrails, giving you control over your agents’ behavior and data handling. +This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. NemoClaw pairs hosted models on inference providers or local endpoints with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. -The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). -NemoClaw adds the blueprint, CLI, onboarding, and related tooling as the reference way to run supported agents there. +The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell); NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run OpenClaw there. | Capability | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| Sandbox supported agents | Creates an OpenShell sandbox pre-configured for your selected agent, with filesystem and network policies applied from the first boot. | +| Sandbox OpenClaw | Creates an OpenShell sandbox pre-configured for OpenClaw, with filesystem and network policies applied from the first boot. | | Route inference | Configures OpenShell inference routing so agent traffic goes to the provider and model you chose during onboarding (NVIDIA Endpoints, OpenAI, Anthropic, Gemini, compatible endpoints, local Ollama, and others). The agent uses `inference.local` inside the sandbox; credentials stay on the host. | | Manage the lifecycle | Handles blueprint versioning, digest verification, and sandbox setup. | @@ -24,7 +23,6 @@ NemoClaw provides the following product capabilities. | Feature | Description | |---------|-------------| | Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. | -| Agent skills | Packages NemoClaw documentation as user skills so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. | | Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. | | State management | Safe migration of agent state across machines with credential stripping and integrity verification. | | Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | @@ -39,19 +37,19 @@ NemoClaw provides the following benefits to mitigate these risks. | Benefit | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------| -| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. The sandbox grants no access by default. | -| Routed inference | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). | -| Declarative network policy | YAML defines egress rules. OpenShell blocks unknown hosts and surfaces them to the operator for approval. | -| Single CLI | The command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | +| Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | +| Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to Inference Options (use the `nemoclaw-user-configure-inference` skill). | +| Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | +| Single CLI | The `nemoclaw` command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | | Blueprint lifecycle | Versioned blueprints handle sandbox creation, digest verification, and reproducible setup. | ## Use Cases -You can use NemoClaw for use cases such as the following. +You can use NemoClaw for various use cases including the following. | Use Case | Description | |---------------------------|----------------------------------------------------------------------------------------------| -| Always-on assistant | Run a sandboxed agent with controlled network access and operator-approved egress. | +| Always-on assistant | Run an OpenClaw assistant with controlled network access and operator-approved egress. | | Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | | Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | @@ -59,21 +57,7 @@ You can use NemoClaw for use cases such as the following. Navigate to the following topics to learn more about NemoClaw and how to install and use it. - - - [Architecture Overview](how-it-works.md) to understand how NemoClaw works. -- [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. +- [Ecosystem](ecosystem.md) to understand how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. +- Quickstart (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first sandboxed agent. - Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works. - - - - -- [Architecture Overview](how-it-works.md) to understand how NemoClaw works. -- [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. -- 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/skills/nemoclaw-user-overview/references/release-notes.md b/skills/nemoclaw-user-overview/references/release-notes.md index 77747019bf..b5d7f664df 100644 --- a/skills/nemoclaw-user-overview/references/release-notes.md +++ b/skills/nemoclaw-user-overview/references/release-notes.md @@ -1,81 +1,8 @@ + + # Release Notes -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.60 - -NemoClaw v0.0.60 improves runtime guidance, sandbox lifecycle reliability, local inference setup, messaging enrollment, and maintainer safeguards: - -- OpenClaw runtime guidance stays active without appearing in the visible chat transcript, and sandbox network and filesystem context now tells agents to try allowed in-sandbox actions before reporting them unavailable. OpenClaw device-approval policy also uses the same allowlist and scope behavior during startup and connect. For more information, refer to Architecture (use the `nemoclaw-user-reference` skill). -- Onboarding and sandbox lifecycle paths preserve more host state. NemoClaw uses the package-managed OpenShell gateway user service when available, scopes gateway and dashboard cleanup by sandbox instance, detects Docker-driver sandboxes without writing the local gateway marker, rolls back failed Docker GPU patches, honors `.dockerignore` for custom `--from ` contexts, and can skip default workspace-template seeding with `NEMOCLAW_MINIMAL_BOOTSTRAP=1`. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Local inference setup is more predictable across NVIDIA NIM, Ollama, vLLM, DGX Spark, DGX Station, Anthropic-compatible routes, and Hermes. NemoClaw pulls NIM images by platform digest, uses stable managed-vLLM images and updated DGX model profiles, tightens Ollama fit checks, synchronizes Anthropic route metadata, preserves Hermes proxy API-key placeholders, and serves the prebuilt Hermes dashboard assets from the sandbox image. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). -- Messaging and day-two CLI operations share more common plumbing. Messaging enrollment uses manifest hooks across Telegram, Discord, Slack, WeChat, and WhatsApp, `nemoclaw tunnel status` reports Cloudflare tunnel state directly, global `status` and `list` honor sandbox environment overrides consistently, and installed OpenClaw skills are mirrored into the agent home directory for session startup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). -- Policy and secret-handling safeguards cover more edge cases. Non-interactive `NEMOCLAW_POLICY_TIER` validation fails before side effects, interactive onboarding ignores invalid environment values and prompts normally, safe common egress presets are available where supported, persistent-memory scanning catches additional OpenAI and Slack token shapes, and Hermes remote secrets stay out of sandbox-visible surfaces. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). - -## v0.0.59 - -NemoClaw v0.0.59 improves OpenClaw runtime compatibility, inference setup, credential reuse, messaging safeguards, and sandbox startup diagnostics: - -- OpenClaw sandboxes stay aligned with the live gateway and current runtime layout. Sandbox startup reconciles the agent model from the live gateway, refreshes the OpenClaw plugin registry after gateway startup, pins OpenClaw home, state, and workspace paths inside the sandbox, and handles OpenClaw 2026.5.27 approval compatibility. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Inference setup has newer model choices and longer first-start budgets for local runtimes. NVIDIA Endpoints includes the Nemotron 3 Ultra 550B option, Local Ollama uses `qwen3.5:9b` as the starter fallback, managed vLLM on DGX Spark uses a 128K context window for `nvidia/Qwen3.6-35B-A3B-NVFP4`, and Local NVIDIA NIM waits longer for first container startup while still failing fast when the container exits. For more information, refer to NemoClaw Inference Options (use the `nemoclaw-user-configure-inference` skill). -- Hermes sandboxes can route Anthropic Messages API traffic through managed inference, and runtime model switches keep the Hermes config synchronized with the OpenShell route. For more information, refer to Switch Inference Models at Runtime (use the `nemoclaw-user-configure-inference` skill). -- Credential and messaging boundaries are clearer during day-two operations. Rebuild and remote-provider update paths can reuse credentials already stored in the OpenShell gateway when the host environment is empty, `channels add` warns or aborts before multiple sandboxes compete for the same token-based messaging credential, and `status` reports cross-sandbox channel overlaps. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). -- Sandbox startup and host preflight failures provide more actionable recovery guidance. NemoClaw heals `~/.nemoclaw` directory and config-file permissions on read paths, detects missing or stale NVIDIA CDI specs before GPU containers fail, probes legacy gateway containers before host-alias operations, and preserves argument validation before runtime probing. For more information, refer to Troubleshooting (use the `nemoclaw-user-reference` skill). - -## v0.0.58 - -NemoClaw v0.0.58 improves GPU proof reporting, local-inference metadata, policy failure handling, Hermes messaging reliability, OpenClaw diagnostics, and release-prep documentation: - -- GPU and local-inference setup report more accurate state. WSL Docker Desktop on ARM64 can accept a reported NVIDIA GPU only after a bounded Docker CUDA proof succeeds, `nemoclaw status` shows whether sandbox CUDA usability is verified, unverified, or failed, managed vLLM uses runtime `max_model_len` metadata for the baked context window when available, and DeepSeek managed-vLLM startup receives the runtime keyword arguments it expects. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). -- Onboarding and installer failures stop earlier with clearer recovery guidance. The installer checks for `strings` from `binutils` before clone, build, or OpenShell download work; Docker-driver gateway startup fails fast when Docker is unreachable; WSL Docker Desktop diagnostics explain unsupported native Docker-in-WSL routes; Windows-host Ollama detection also checks the installed Windows process when the daemon is stopped; and custom proxy host and port settings are forwarded into the runtime container. For more information, refer to Prerequisites (use the `nemoclaw-user-get-started` skill). -- Policy and sandbox hardening paths avoid misleading success. `policy-add` refuses to merge a preset when the live policy read returns unparseable output, custom preset application reports when the gateway accepted a preset but the sandbox registry could not record it, and `NEMOCLAW_REQUIRE_CAP_DROP=1` lets operators make entrypoint capability dropping fail closed. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- OpenClaw runtime diagnostics can export conversation traces through the `diagnostics-otel` plugin. Set `NEMOCLAW_OPENCLAW_OTEL=1` before onboarding or rebuilding an OpenClaw sandbox to bake the plugin config and apply the local OTLP policy preset. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Hermes sandboxes are more reliable across messaging, inference, and startup repair paths. Slack channel rebuilds enable the Hermes Slack platform block, `inference.local` routes include the placeholder API key LiteLLM expects, Telegram pseudo-tool text is normalized only for the active chat platform, the messaging response patch preserves Hermes method binding, retry markers are cleared before explicit command dispatch, and Hermes state repair preserves writable history and background dispatcher behavior in locked runtime state. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). - -## v0.0.57 - -NemoClaw v0.0.57 improves multi-agent command workflows, local inference setup, messaging channel reliability, sandbox diagnostics, policy persistence, and installer pinning: - -- OpenClaw sandboxes can manage conversation sessions and secondary agents from the host CLI. Use `nemoclaw sessions` to list sessions, reset a session key through the OpenClaw gateway, or delete a non-main session, and use `nemoclaw agents add` or `nemoclaw agents delete` to invoke the in-sandbox OpenClaw agent commands. Build-time config also accepts `NEMOCLAW_EXTRA_AGENTS_JSON` so operators can bake validated secondary-agent entries into `agents.list` without replacing the primary `main` agent. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Local inference setup is more observable and more resilient. Managed vLLM on DGX Spark defaults to `nvidia/Qwen3.6-35B-A3B-NVFP4`, streams Hugging Face model-download progress, polls `/v1/models` for readiness, and uses a progress-aware Docker pull watchdog. Local Ollama routes request streaming usage metadata so OpenClaw token counters can update, and `connect` warns when the recorded inference route diverges from the live gateway route instead of reverting silently. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). -- Onboarding and re-onboarding preserve more operator intent. Linux Docker-driver onboarding can auto-apply a narrow UFW rule for the sandbox-to-gateway bridge when `NEMOCLAW_AUTO_FIX_FIREWALL=1`, verifies host-network local-inference reachability before reporting success, reuses healthy containerized gateways, binds gateway state by port, rolls back a freshly-created sandbox when setup is cancelled at the policy preset step, and carries finalized policy preset selections across later re-onboard runs. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Messaging channel setup fails earlier and leaves fewer partial changes. Slack setup validates both Socket Mode tokens before saving credentials, `channels add` checks the matching built-in policy preset before prompting or persisting channel state, failed preset application rolls back staged bridge changes when possible, WhatsApp pairing renders a compact QR code with clearer gateway diagnostics, and Slack runtime placeholders are normalized before OpenClaw starts. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). -- Sandbox status and repair output are more actionable. `nemoclaw status` reports Docker daemon, stopped-container, dashboard-port-conflict, and paused-container layers without running misleading inference probes, `doctor` skips stale Kubernetes-only gateway container checks on Docker-driver installs, and stale local registry entries are preserved so the suggested `rebuild --yes` recovery path still has the metadata it needs. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Installer and policy guidance tightened. Piped installs show the correct `NEMOCLAW_INSTALL_TAG` placement and fail clearly when a requested ref is unavailable, the `pypi` preset allows the `uv` package manager binary, and Jira validation now uses a body-visible Atlassian API probe so operators can distinguish blocked and approved curl traffic. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). - -## v0.0.56 - -NemoClaw v0.0.56 improves install safety, local-inference validation, messaging diagnostics, sandbox lifecycle reporting, and day-two command behavior: - -- Public installer and `nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill). -- `nemoclaw status`, `nemoclaw connect`, and `nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). -- Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). -- Command ergonomics are clearer for common day-two paths. `nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `nemoclaw status --json` supports per-sandbox automation, and `nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to NemoClaw CLI Commands Reference (use the `nemoclaw-user-reference` skill). -- Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to Common NemoClaw Integration Policy Examples (use the `nemoclaw-user-manage-policy` skill). -- Uninstall, rebuild, and snapshot flows protect user state more consistently. `nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to Manage Sandbox Lifecycle (use the `nemoclaw-user-manage-sandboxes` skill). - -## v0.0.55 - -NemoClaw v0.0.55 improves local Ollama onboarding reliability, plugin secret-scanner resilience, and messaging-channel prompt clarity: - -- Local Ollama validation retries host-side curl process timeouts with a larger timeout before failing, and Docker runtime detection retries `docker info` before choosing the local inference route. For more information, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). -- The NemoClaw OpenClaw plugin keeps the memory secret scanner active when OpenClaw runs in embedded fallback mode without a usable path resolver. The scanner falls back to literal memory and workspace-relative paths instead of crashing before the first write-tool call. For more information, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). -- The onboarding messaging-channel picker now states that pressing Enter with no channels selected skips messaging setup. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). - -## v0.0.54 - -NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHermes dashboard access, and sandbox repair paths: - -- Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to Messaging Channels (use the `nemoclaw-user-manage-sandboxes` skill). -- 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). -- 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). +NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track changes. ## v0.0.53 @@ -290,20 +217,20 @@ NemoClaw v0.0.38 improves several day-two workflows: Starting with NemoClaw v0.0.34, the `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash` installer pipeline no longer auto-accepts the third-party software notice when stdin is piped and `/dev/tty` is unavailable (for example, deeply detached SSH sessions or some container shells). In environments without a TTY, accept upfront in the pipe: -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +```console +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash ``` Or pass the flag through to the installer: -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software +```console +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software ``` Or re-run from a terminal with a controlling TTY: -```bash -bash <(curl -fsSL https://www.nvidia.com/nemoclaw.sh) +```console +$ bash <(curl -fsSL https://www.nvidia.com/nemoclaw.sh) ``` The installer error message in v0.0.35+ surfaces all three invocations directly so users can copy-paste a recovery without leaving the terminal. diff --git a/skills/nemoclaw-user-reference/SKILL.md b/skills/nemoclaw-user-reference/SKILL.md index 6d57867d78..25cb810e52 100644 --- a/skills/nemoclaw-user-reference/SKILL.md +++ b/skills/nemoclaw-user-reference/SKILL.md @@ -9,7 +9,7 @@ license: "Apache-2.0" ## References - **Load [references/architecture.md](references/architecture.md)** when looking up architecture, agent integration, plugin structure, or blueprint design. Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. -- **Load [references/cli-selection-guide.md](references/cli-selection-guide.md)** when user asks to decide whether to use `$$nemoclaw` or `openshell`. Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. +- **[references/cli-selection-guide.md](references/cli-selection-guide.md)** — Explains when to use `$$nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations. - **Load [references/commands.md](references/commands.md)** when looking up a specific `$$nemoclaw`, `nemohermes`, or `/nemoclaw` subcommand, flag, argument, or exit code. Includes the full CLI reference for standalone NemoClaw commands and agent-specific in-sandbox commands. - **Load [references/network-policies.md](references/network-policies.md)** when looking up a specific default endpoint, filesystem path, or the runtime approval sequence NemoClaw applies on blocked requests. Covers the baseline network policy, filesystem rules, and operator approval flow. - **Load [references/troubleshooting.md](references/troubleshooting.md)** when diagnosing a reported NemoClaw error, a failed onboard, or unexpected sandbox behavior. Lists fixes for common installation, onboarding, and runtime issues. diff --git a/skills/nemoclaw-user-reference/references/architecture.md b/skills/nemoclaw-user-reference/references/architecture.md index 18ecd28a49..07bbfc2ba9 100644 --- a/skills/nemoclaw-user-reference/references/architecture.md +++ b/skills/nemoclaw-user-reference/references/architecture.md @@ -68,13 +68,9 @@ graph LR The logical diagram above shows how components relate. This section shows what actually runs where on the host. NemoClaw's default Docker-driver topology does not place the sandbox in an embedded k3s cluster. -On Linux, NemoClaw configures and restarts the package-managed OpenShell gateway user service when it is installed, then creates the sandbox as a Docker container. -NemoClaw treats that service as authoritative only when `systemctl --user show openshell-gateway` reports a package/vendor unit path and an `openshell-gateway` `ExecStart`. -Per-user units, partial units, and user-manager or bus outages do not take over gateway ownership; NemoClaw falls back to the standalone gateway process used by earlier installs. -That compatibility fallback remains until supported upgrade paths no longer include pre-service OpenShell installs and the package-managed handoff has direct nightly coverage. -On Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. +On Linux and Apple Silicon macOS, NemoClaw starts the OpenShell Docker-driver gateway and creates the sandbox as a Docker container. +The gateway normally runs as a host process; Linux hosts that need the gateway compatibility patch may run the same gateway binary inside a small container. In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod. -When `OPENSHELL_DRIVERS` includes `docker`, NemoClaw treats the gateway as host-owned and does not write the in-container `/tmp/nemoclaw-gateway-local` marker that legacy in-container gateway paths use. Legacy non-Docker-driver installs still use the k3s-based gateway path; the diagram below shows the standard Docker-driver topology. ```mermaid @@ -138,10 +134,8 @@ The concrete files differ by agent because each runtime has its own plugin syste | Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. -Before an OpenClaw turn starts, the plugin prepends a short system-context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. -This guidance stays out of the visible chat transcript. +Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. -The context tells the agent to try allowed network and filesystem operations before reporting them unavailable, and to distinguish policy denials from DNS, timeout, TLS, or filesystem errors. The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint. @@ -203,7 +197,7 @@ runner still carries a pinned OpenShell Community OpenClaw image for legacy - Inference calls are routed through OpenShell to the configured provider. - Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. -- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can attempt allowed actions and report policy blocks or infrastructure failures accurately. +- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. diff --git a/skills/nemoclaw-user-reference/references/commands.md b/skills/nemoclaw-user-reference/references/commands.md index d5db5d01a1..4a632f4f6a 100644 --- a/skills/nemoclaw-user-reference/references/commands.md +++ b/skills/nemoclaw-user-reference/references/commands.md @@ -33,7 +33,7 @@ OpenClaw-specific sections below describe the `/nemoclaw` slash command, the Ope Use `nemohermes` for the Hermes variant. It selects Hermes by default during onboarding and for other commands. Use `--agent hermes` during onboarding or set `NEMOCLAW_AGENT=hermes` when you need the same selection through another entry point. -Hermes-specific sections below describe the built-in Hermes dashboard, the separate OpenAI-compatible API endpoint, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. +Hermes-specific sections below describe the OpenAI-compatible API endpoint, optional Hermes dashboard, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. ```bash nemohermes onboard # selects Hermes by default @@ -173,10 +173,6 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `bal NEMOCLAW_POLICY_TIER=restricted nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` -Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -In non-interactive mode, any non-blank value must be one of `restricted`, `balanced`, 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 policy-add`](#nemoclaw-name-policy-add) across re-onboards. @@ -185,12 +181,6 @@ 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, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. - - -Hermes managed-tool gateway selections add matching Hermes-specific policy presets, such as `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`, without applying unsupported OpenClaw-only presets. - - - | Value | Behaviour | |-------|-----------| | `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | @@ -309,10 +299,9 @@ The poll count is clamped to a minimum of `1` so the probe always runs at least Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. -If that directory contains a `.dockerignore`, onboarding applies those rules while calculating the context size and staging files for Docker. -NemoClaw also applies additional secret-safety exclusions that override `.dockerignore` negation rules: credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key` are still skipped even if `.dockerignore` tries to include them. -Without a `.dockerignore`, onboarding still skips common large or local-only directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. -Other build outputs such as `dist/`, `target/`, or `build/` are included unless your `.dockerignore` excludes them. +Onboarding skips common large directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. +It also skips credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`. +Other build outputs such as `dist/`, `target/`, or `build/` are still included. If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts. 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. @@ -398,7 +387,6 @@ 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. ```bash nemoclaw list [--json] @@ -579,7 +567,7 @@ Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a new ```console $ nemoclaw my-assistant status ... - Agent: OpenClaw v2026.5.27 + Agent: OpenClaw v2026.5.22 ... ``` @@ -618,35 +606,10 @@ Warnings do not make the command fail. Failed checks exit non-zero so scripts can use `doctor` as a readiness gate. Use `--json` for machine-readable output. - - -For OpenClaw sandboxes, `doctor` also checks the mutable config permission contract. -If `openclaw doctor --fix` was run inside the sandbox, it can tighten `/sandbox/.openclaw` and `openclaw.json` to a single-user `700/600` layout, which stops the gateway from persisting config changes. -`doctor` reports this as a `Config permissions` warning; pass `--fix` to restore the group-writable `2770/660` contract without rebuilding. -Restarting the sandbox repairs the same drift automatically. - -```bash -nemoclaw my-assistant doctor [--json | --fix] -``` - -| Flag | Description | -|------|-------------| -| `--json` | Emit the report as JSON | -| `--fix` | Restore the mutable OpenClaw config permission contract if it was tightened. Mutually exclusive with `--json` | - - - - ```bash nemoclaw my-assistant doctor [--json] ``` -| Flag | Description | -|------|-------------| -| `--json` | Emit the report as JSON | - - - ### `nemoclaw logs` View sandbox logs. @@ -665,9 +628,7 @@ nemoclaw my-assistant logs [--follow] [--tail |-n ] [--since -Print the browser dashboard URL for a running sandbox. -For OpenClaw sandboxes this includes the authenticated URL fragment. -For agent dashboards that manage their own session, such as Hermes Agent, this prints the plain dashboard URL. +Print the authenticated OpenClaw dashboard URL for a running sandbox. Use this when you are on a remote machine, using an SSH or reverse tunnel, or need a complete URL for a browser session. ```bash @@ -686,22 +647,14 @@ URL=$(nemoclaw my-assistant dashboard-url --quiet) Treat the authenticated dashboard URL like a password. Do not log it, share it, or commit it to version control. -This warning applies when the command prints an OpenClaw tokenized URL. -Print the browser dashboard URL for a running Hermes sandbox. -Hermes manages dashboard sessions itself, so this command prints a plain URL without an OpenClaw `#token=` fragment. -The built-in dashboard is forwarded on port `18789` by default. - -```bash -nemohermes my-assistant dashboard-url -nemohermes my-assistant dashboard-url --quiet -``` - -The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for OpenAI-compatible clients. -Use `nemohermes my-assistant status` to see both the dashboard and API endpoints. +`dashboard-url` is not applicable to Hermes sandboxes because Hermes exposes an OpenAI-compatible API endpoint instead of the OpenClaw dashboard URL. +Use `nemohermes my-assistant status` to find the forwarded API endpoint. +The Hermes API remains on port `8642` and uses `/v1` for OpenAI-compatible clients. +If you enabled `NEMOCLAW_HERMES_DASHBOARD=1`, use the optional Hermes dashboard port from the status output instead. @@ -819,8 +772,6 @@ Custom presets bypass the built-in preset review process and can widen sandbox e List available policy presets and show which ones are applied to the sandbox. 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. ```bash nemoclaw my-assistant policy-list @@ -1024,9 +975,6 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see Install OpenClaw Plugins. -For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory. -That mirror makes skills listed by `openclaw skills list` available at session startup. -If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions. @@ -1425,16 +1373,6 @@ nemoclaw tunnel stop `nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`. -### `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. - -```console -nemoclaw tunnel status -``` - ### `nemoclaw start` **Warning:** @@ -1456,7 +1394,6 @@ This command remains as a compatibility alias to `nemoclaw tunnel stop`. Show the sandbox list and the status of host auxiliary services (for example cloudflared). Pass `--json` for machine-readable output with registered sandboxes, service state, inference routes, and messaging health. For each listed sandbox, the text output includes the configured inference provider and model plus whether an active SSH session is connected. -Host-service PID lookup honors `NEMOCLAW_SANDBOX_NAME`, then `NEMOCLAW_SANDBOX`, then `SANDBOX_NAME`, then the registry default. ```bash nemoclaw status @@ -1493,8 +1430,7 @@ For OpenClaw, the patch updates the OpenClaw config provider namespace and selec -For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) and does not rebuild or restart the gateway. -Keeping the placeholder preserves dashboard and API authentication after provider switches. +For Hermes, the patch updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) and does not rebuild or restart the gateway. Under the `nemohermes` alias, it uses the registered Hermes sandbox when exactly one exists; otherwise pass `--sandbox ` to target one explicitly. @@ -1612,7 +1548,7 @@ Earlier releases only stopped `openshell forward` processes, so those orphans ac 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. +On Linux, uninstall removes `~/.local/state/nemoclaw`, which contains Docker-driver gateway PID files, SQLite data, audit logs, and VM-driver state. | Flag | Effect | |---|---| @@ -1754,14 +1690,15 @@ For OpenClaw, `NEMOCLAW_DASHBOARD_PORT` controls the OpenClaw dashboard forward. -For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the built-in dashboard forward, which defaults to `18789`. -The Hermes OpenAI-compatible API remains separate on port `8642` and uses `/v1` for API clients. -Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-browser TUI tab. +For Hermes, `NEMOCLAW_DASHBOARD_PORT` controls the OpenAI-compatible API forward. +For Hermes sandboxes, `NEMOCLAW_HERMES_DASHBOARD=1` starts the native Hermes dashboard separately from the OpenAI-compatible API. +The Hermes API remains on port `8642`; the optional browser dashboard uses `NEMOCLAW_HERMES_DASHBOARD_PORT`. | Variable | Default | Service | |----------|---------|---------| -| `NEMOCLAW_DASHBOARD_PORT` | 18789 | Hermes built-in dashboard forward port | -| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab | +| `NEMOCLAW_HERMES_DASHBOARD` | 0 | Optional Hermes native web dashboard (`1`, `true`, `yes`, or `on` enables it) | +| `NEMOCLAW_HERMES_DASHBOARD_PORT` | 9119 | Optional Hermes native web dashboard forward port | +| `NEMOCLAW_HERMES_DASHBOARD_TUI` | 0 | Optional Hermes in-browser TUI tab when the dashboard is enabled | @@ -1785,13 +1722,10 @@ Set them before running `nemoclaw onboard`. | `NEMOCLAW_OPENCLAW_OTEL_SERVICE_NAME` | service name | Sets the OTEL `service.name` for OpenClaw gateway spans. Defaults to `openclaw-gateway`. | | `NEMOCLAW_OPENCLAW_OTEL_SAMPLE_RATE` | `0.0` to `1.0` | Sets OpenClaw's root-span sample rate for conversation diagnostics. Defaults to `1.0`. | | `NEMOCLAW_OPENSHELL_BIN` | path | Overrides the `openshell` binary the CLI invokes. Defaults to `openshell` (resolved via `PATH`). | -| `NEMOCLAW_SANDBOX_NAME` | sandbox name | Preferred environment override for the default sandbox. Used by onboarding defaults and host-level commands such as `list`, `status`, `tunnel`, `services`, and `debug`. | -| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | -| `SANDBOX_NAME` | sandbox name | Compatibility spelling used after `NEMOCLAW_SANDBOX_NAME` and `NEMOCLAW_SANDBOX`. | +| `NEMOCLAW_SANDBOX` | sandbox name | Alternate spelling of `NEMOCLAW_SANDBOX_NAME`; used by `services` and `debug` lookups when neither a flag nor `NEMOCLAW_SANDBOX_NAME` is set. | | `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: `deepseek-v4-flash`, `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `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_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_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-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_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). | @@ -1817,8 +1751,6 @@ Hermes-specific provider authentication: | `NEMOCLAW_HERMES_AUTH_METHOD` | `oauth` | Selects Hermes Provider authentication in non-interactive onboarding. Valid values: `oauth`, `nous-portal-oauth`, `api-key`, `nous-api-key`. | | `NEMOCLAW_HERMES_AUTH` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Back-compatible alias for Hermes Provider authentication selection. | | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | -| `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | -| `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | @@ -1898,9 +1830,9 @@ These flags toggle optional behaviors during onboarding; set them before running | `NEMOCLAW_SANDBOX_GPU` | `auto`, `1`, or `0` | Controls sandbox GPU passthrough during onboarding. `auto` enables GPU passthrough when an NVIDIA GPU is detected, `1` requires GPU passthrough, and `0` forces CPU-only sandbox creation. | | `NEMOCLAW_SANDBOX_GPU_DEVICE` | OpenShell GPU device selector | Selects the GPU device passed with `openshell sandbox create --gpu-device`. Requires explicit sandbox GPU enablement with `NEMOCLAW_SANDBOX_GPU=1` (or `--sandbox-gpu` for CLI-driven onboarding); otherwise onboarding rejects the selector instead of treating it as an implicit opt-in. | | `NEMOCLAW_DOCKER_GPU_PATCH` | `0` to disable, anything else to keep the default | Controls the Linux Docker-driver GPU sandbox compatibility patch. Set to `0` only as an escape hatch when the patch fails and you need onboarding to continue without patching the GPU sandbox container. | -| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. | -| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary used by the Linux Docker-driver standalone fallback. Defaults to the binary next to `openshell`, then common install paths. | -| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway SQLite state directory and standalone-fallback PID file. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. | +| `NEMOCLAW_OPENSHELL_GATEWAY_BIN` | path | Advanced override for the `openshell-gateway` binary used by the Linux Docker-driver gateway. Defaults to the binary next to `openshell`, then common install paths. | +| `NEMOCLAW_OPENSHELL_SANDBOX_BIN` | path | Advanced override for the `openshell-sandbox` binary passed to the Linux Docker-driver gateway supervisor. Defaults to the binary next to `openshell`, then common install paths. | +| `NEMOCLAW_OPENSHELL_GATEWAY_STATE_DIR` | path | Advanced override for the Linux Docker-driver gateway pid file and SQLite state directory. Defaults to `~/.local/state/nemoclaw/openshell-docker-gateway`. | | `NEMOCLAW_AUTO_FIX_FIREWALL` | `1` to enable | Opts in to automatic UFW remediation when Linux Docker-driver sandbox containers cannot reach the host gateway after a proven TCP failure. NemoClaw runs `sudo -n` only, validates the narrow Docker bridge subnet → gateway IP:port rule before invoking UFW, re-probes after applying it, and otherwise falls back to the printed manual command. | | `NEMOCLAW_WECHAT_QUIET` | `1` to enable | Silences the `[wechat]` diagnostic lines printed during the host-side WeChat QR login (poll status, IDC redirects, swallowed gateway errors), which are visible by default while the experimental WeChat path stabilizes; set `1` once the flow is reliable in your environment. | diff --git a/skills/nemoclaw-user-reference/references/network-policies.md b/skills/nemoclaw-user-reference/references/network-policies.md index 937dd41abe..de3517a690 100644 --- a/skills/nemoclaw-user-reference/references/network-policies.md +++ b/skills/nemoclaw-user-reference/references/network-policies.md @@ -57,14 +57,13 @@ The baseline policy is always applied regardless of the selected tier. | Tier | Presets included | Description | |------|------------------|-------------| | Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather` | Full dev tooling, read-only weather lookups, and web search for agents that support web search. No messaging platform access. | -| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `weather`, `public-reference`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging, productivity, weather, and public-reference APIs. | +| Balanced (default) | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported` | Full dev tooling and web search for agents that support web search. No messaging platform access. | +| Open | `npm`, `pypi`, `huggingface`, `brew`, `brave when supported`, `slack`, `discord`, `telegram`, `wechat` (experimental), `whatsapp` (experimental), `jira`, `outlook` | Broad access across third-party services including messaging and productivity. | After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access. Tier-default presets are pre-selected; additional presets can be added from the full list. NemoClaw filters tier defaults by the active agent's supported integrations. For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration. -Hermes managed-tool gateway selections can add Hermes-specific presets, such as Nous-hosted web, image, audio, browser, or code tools, without applying unsupported OpenClaw-only presets. Claude Code direct egress is not included in any policy tier. If you install and run the Claude Code CLI inside the sandbox with its own credentials, apply the `claude-code` preset explicitly. Normal NemoClaw Anthropic inference still routes through the OpenShell gateway. @@ -77,9 +76,7 @@ In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER`: NEMOCLAW_POLICY_TIER=open nemoclaw onboard --non-interactive --yes-i-accept-third-party-software ``` -Unset, blank, or whitespace-only `NEMOCLAW_POLICY_TIER` values use the `balanced` default. -In non-interactive onboarding, a non-blank value that does not match a known tier exits before preflight, gateway, or inference side effects and lists the valid options. -Interactive onboarding ignores an invalid environment value and shows the normal tier prompt. +If the value does not match a known tier, onboarding exits with an error listing the valid options. ### Inference diff --git a/skills/nemoclaw-user-reference/references/troubleshooting.md b/skills/nemoclaw-user-reference/references/troubleshooting.md index 3d85d5f1be..cdafbeb91a 100644 --- a/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -660,8 +660,6 @@ Region errors usually mean the pasted endpoint region, `AWS_REGION`, `AWS_DEFAUL For Ollama, vLLM, NIM, and compatible-endpoint inference validation, the default timeout is 180 seconds. The managed NIM startup health wait uses a separate 15-minute (900-second) default and still exits early if the container stops before it becomes healthy. -On Docker 29.x or hosts using the containerd image store, managed NIM onboarding resolves and pulls the host-platform image digest when NGC exposes a multi-architecture image index. -If you still see NGC repository-format or attestation errors, confirm Docker can run `docker manifest inspect` for the selected image and that you are logged in to `nvcr.io`. If large prompts still cause timeouts, increase it with `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` before re-running onboard: ```bash @@ -670,7 +668,6 @@ nemoclaw onboard ``` For local Ollama and vLLM, onboarding retries the container reachability check and can fall back to the host-side health check when the local backend is healthy. -If Ollama times out during a cold model load, NemoClaw retries once with a 300-second probe budget before failing. If all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution. `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only covers the inference-server validation probe. @@ -840,37 +837,7 @@ Do not treat a failed `doctor --fix` run as proof that the Discord gateway path If `openclaw doctor` reports that it moved Telegram single-account values under `channels.telegram.accounts.default`, rerun onboarding and rebuild the sandbox rather than trying to patch `openclaw.json` in place. Current NemoClaw rebuilds bake Telegram in the account-based layout and set Telegram group chats to `groupPolicy: open`, which avoids the empty `groupAllowFrom` warning path for default group-chat access. -### `openclaw doctor --fix` tightened config permissions and the gateway can no longer save config - -In a mutable NemoClaw sandbox, the gateway UID and the sandbox UID share the `sandbox` group, so `/sandbox/.openclaw` is setgid and group-writable (`2770`) and `openclaw.json` is group-writable (`660`). -OpenClaw's `openclaw doctor --fix` enforces its own single-user `700/600` layout, so running it inside the sandbox strips group write and breaks gateway-side config writes (for example, control-UI toggles that mutate `openclaw.json`). - -Repair the mutable contract without rebuilding: - -```bash -nemoclaw doctor --fix -``` - -`nemoclaw doctor` reports the drift as a `Config permissions` warning, and `--fix` restores `2770/660`. -Restarting the sandbox repairs the same drift automatically, and NemoClaw's own `rebuild` re-applies the contract after its post-upgrade `openclaw doctor --fix` step. - -When verifying gateway write access by hand, step down to the gateway UID with the image's installed mechanism so the `sandbox` group membership is initialized: - -```bash -setpriv --reuid=gateway --regid=gateway --init-groups -- sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json' -# or, where setpriv is unavailable: -gosu gateway sh -c 'echo ok >> /sandbox/.openclaw/openclaw.json' -``` - -Do not probe with `su -s /bin/sh gateway ...`: `su` does not initialize the gateway's supplementary groups the same way, so a group-write probe can spuriously report `EACCES` even when the mutable contract is intact. - -A NemoClaw sandbox has two intentional permission states for `/sandbox/.openclaw`; `700/600` is not one of them: - -- **Mutable default:** `/sandbox/.openclaw` is `2770 sandbox:sandbox` and `openclaw.json` is `660 sandbox:sandbox`. Both the sandbox user and the gateway (same `sandbox` group, different UID) can write config, so control-UI toggles persist. -- **Host-locked state:** `openclaw.json` is read-only for in-sandbox writers and the config dir is owned by `root`, with the immutable bit set where available. No in-sandbox writes are expected; use the host-side `nemoclaw config set` flow described in [`openclaw config set` fails with a permission error on Brev](#openclaw-config-set-fails-with-a-permission-error-on-brev). -- **`700/600` (drift):** the layout that upstream `openclaw doctor --fix` imposes inside a mutable sandbox. It is not a supported NemoClaw state; recover with `nemoclaw doctor --fix` or a sandbox restart. - -## Discord bot logs in, but the channel still does not work +### Discord bot logs in, but the channel still does not work Separate the problem into two parts: @@ -1284,9 +1251,6 @@ If onboarding reports `OpenShell supervisor did not reconnect to the GPU-enabled The reconnect wait debounces consecutive Error-phase polls before fast-failing, defaulting to fifteen consecutive polls of about 30 seconds in total. Increase the debounce window with `NEMOCLAW_DOCKER_GPU_SUPERVISOR_RECONNECT_ERROR_DEBOUNCE` if your host needs more time to re-register the patched container, for example slow WSL2 + Docker Desktop setups. Set it to a higher integer such as `30` (about 60 seconds) and rerun onboarding; the value is clamped to a minimum of `1`. -If reconnect still fails after the GPU patch, NemoClaw attempts to restore the pre-patch CPU container before exiting. -When rollback succeeds, the output says the pre-patch sandbox was restored. -When rollback fails, the error says rollback failed and the pre-patch container was not restored, so inspect Docker state before retrying. ### `pip install` fails with a system-packages error @@ -1355,8 +1319,6 @@ If the process exists but the endpoint is unreachable, use the restart action wh Ollama configures context length based on your hardware. On some GPUs (for example RTX 3500), the default context length is not sufficient for OpenClaw. -During onboarding, NemoClaw raises loaded-model context lengths below `16384` to `16384` when `NEMOCLAW_CONTEXT_WINDOW` is unset. -Set the variable manually when you need a different value or when you run Ollama outside the managed onboarding path. Force a larger context length: ```bash From 92d8988bbdf0a87475eb6293178a1bbea20f3f30 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 5 Jun 2026 18:53:15 -0700 Subject: [PATCH 4/4] docs: keep root skills out of docs refresh --- .agents/skills/nemoclaw-contributor-update-docs/SKILL.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md index e4377a7f4b..495b1250f9 100644 --- a/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md +++ b/.agents/skills/nemoclaw-contributor-update-docs/SKILL.md @@ -181,6 +181,10 @@ If the user invoked this skill for release prep, finish the release-specific doc python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx ``` + Do not include the root `skills/` directory as an output target. That + directory is refreshed by a separate process and must not be updated by this + skill. + ## Step 9: Build and Verify After making changes, build the docs locally: @@ -226,7 +230,7 @@ User says: "Catch up the docs for everything merged since v0.1.0." 4. Read the commit diffs and current doc pages. 5. Draft doc updates reflecting the source code changes in the commits following the style guide. 6. **Release prep only:** Determine the release label from the user-requested release version. -7. **Release prep only:** Run `python3 scripts/docs-to-skills.py docs/ .agents/skills/ skills/ --prefix nemoclaw-user --doc-platform fern-mdx`. +7. **Release prep only:** Run `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx`. Do not update root `skills/`. 8. Present the summary. 9. Build with `npm run docs` to verify. 10. **Release prep only:** Commit changes and open a pull request with the `area: docs`, `area: skills`, and corresponding `vX.Y.Z` release labels. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape: