diff --git a/docs/about/ecosystem-hermes.mdx b/docs/about/ecosystem-hermes.mdx index ec462185c38..f1ee332ee23 100644 --- a/docs/about/ecosystem-hermes.mdx +++ b/docs/about/ecosystem-hermes.mdx @@ -3,7 +3,7 @@ # SPDX-License-Identifier: Apache-2.0 title: "Ecosystem" sidebar-title: "Ecosystem" -description: "How Hermes, OpenShell, and NemoClaw form one stack, where NemoClaw sits, what it adds beyond a DIY OpenShell deployment, and when to use the reference integration versus OpenShell alone." +description: "How Hermes, OpenShell, and NemoClaw form one stack, where NemoClaw sits, what it adds beyond a custom OpenShell deployment, and when to use the reference integration versus OpenShell alone." description-agent: "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. Use when users ask about Hermes, OpenShell, and NemoClaw together, or when to use NemoClaw versus OpenShell for Hermes." keywords: ["nemoclaw ecosystem", "hermes agent", "nemohermes", "nemoclaw vs openshell", "run hermes openshell sandbox"] content: @@ -12,11 +12,11 @@ content: 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 the ecosystem is formed across projects, 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. +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 -There are three pieces in a NemoClaw for Hermes deployment: Hermes, OpenShell, and NemoClaw, each with a distinct scope. +A NemoClaw for Hermes deployment combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid @@ -60,18 +60,18 @@ 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 stand up a known-good Hermes-on-OpenShell setup with less custom glue. | +| **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 DIY OpenShell +## 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 DIY OpenShell integration with `nemohermes onboard`. +The following table compares custom OpenShell integration with `nemohermes onboard`. -| Capability | DIY OpenShell + Hermes | `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. | @@ -94,9 +94,9 @@ Use the following table to decide when to use NemoHermes versus OpenShell alone. | 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 +## Related Topics -- [Overview](overview) contains what NemoClaw is, capabilities, benefits, and use cases. +- [Overview](overview) describes what NemoClaw is, including capabilities, benefits, and use cases. - [How It Works](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes. - [Architecture](../reference/architecture) shows the repository structure and technical diagrams. - [Quickstart with Hermes](../get-started/quickstart-hermes) installs NemoClaw and launches your first Hermes sandbox. diff --git a/docs/about/ecosystem.mdx b/docs/about/ecosystem.mdx index f1ff78d56f5..357ab1a7154 100644 --- a/docs/about/ecosystem.mdx +++ b/docs/about/ecosystem.mdx @@ -11,11 +11,11 @@ content: --- 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 for OpenClaw 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 @@ -59,7 +59,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 @@ -77,7 +77,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. | @@ -94,8 +94,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) contains what NemoClaw is, capabilities, benefits, and use cases. -- [How It Works](how-it-works) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers. +- [Overview](overview) describes what NemoClaw is, including capabilities, benefits, and use cases. +- [How It Works](how-it-works) describes how NemoClaw runs, including the plugin, blueprint, sandbox creation, routing, and protection layers. - [Architecture](../reference/architecture) shows the repository structure and technical diagrams. diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 4e302606a36..268de0b199e 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -47,7 +47,7 @@ For repository layout, file paths, and deeper diagrams, see [Architecture](../re ## Design Principles -NemoClaw architecture follows the following principles. +NemoClaw follows these architecture principles. Versioned blueprint : Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. @@ -60,8 +60,7 @@ 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 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. @@ -79,7 +78,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: -- _Hermes runtime configuration_ is written into `/sandbox/.hermes` during onboarding, including `config.yaml`, environment files, and platform adapter settings for supported messaging channels. +- 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. diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 296a85aa67a..4963bfb9b68 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -16,7 +16,7 @@ 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. -This enables self-evolving agents to run more safely in clouds, on-prem, RTX PCs, and DGX Spark. +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). @@ -50,15 +50,15 @@ 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](../inference/inference-options). | -| Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | +| 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](../inference/inference-options). | +| 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 | |---------------------------|----------------------------------------------------------------------------------------------| diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index 37c01f6a2b4..a78dc68e240 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -9,7 +9,9 @@ keywords: ["nemoclaw release notes", "nemoclaw changelog"] content: type: "reference" --- -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). +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.56 diff --git a/docs/deployment/brev-web-ui.mdx b/docs/deployment/brev-web-ui.mdx index ffceffe2737..b38a8a5a2cc 100644 --- a/docs/deployment/brev-web-ui.mdx +++ b/docs/deployment/brev-web-ui.mdx @@ -36,7 +36,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. @@ -55,7 +56,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. @@ -104,7 +105,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**. @@ -117,7 +119,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/docs/deployment/deploy-to-remote-gpu.mdx b/docs/deployment/deploy-to-remote-gpu.mdx index dc9243bbb0f..6ab522d291d 100644 --- a/docs/deployment/deploy-to-remote-gpu.mdx +++ b/docs/deployment/deploy-to-remote-gpu.mdx @@ -14,20 +14,6 @@ skill: 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: - -```bash -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. - ## Prerequisites - The [Brev CLI](https://brev.nvidia.com) installed and authenticated. @@ -58,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. @@ -90,24 +76,20 @@ 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: ```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. -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. @@ -116,10 +98,10 @@ 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). @@ -130,8 +112,8 @@ 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`](../inference/use-local-inference#timeout-configuration). +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`](../inference/use-local-inference#timeout-configuration). ## Proxy Configuration @@ -144,9 +126,9 @@ 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`. diff --git a/docs/deployment/install-openclaw-plugins.mdx b/docs/deployment/install-openclaw-plugins.mdx index 36b4895ed71..8e7bd525b14 100644 --- a/docs/deployment/install-openclaw-plugins.mdx +++ b/docs/deployment/install-openclaw-plugins.mdx @@ -11,21 +11,19 @@ content: skill: priority: 20 --- -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. ```text my-plugin-sandbox/ @@ -37,8 +35,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 @@ -55,8 +52,7 @@ 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 @@ -66,37 +62,27 @@ Point `nemoclaw onboard --from` at the Dockerfile in the build directory. 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](../reference/network-policies) for -policy concepts and [Customize Network Policy](../network-policy/customize-network-policy) -for custom preset workflows. +For policy concepts, refer to [Network Policies](../reference/network-policies). +For custom preset workflows, refer to [Customize Network Policy](../network-policy/customize-network-policy). ## 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. - 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) before adding plugin code to a - shared or long-lived sandbox. -- Review [Network Policies](../reference/network-policies) to plan plugin - egress rules. -- Follow [Customize Network Policy](../network-policy/customize-network-policy) - if the plugin needs a custom preset. +- Review [Sandbox Hardening](sandbox-hardening) before adding plugin code to a shared or long-lived sandbox. +- Review [Network Policies](../reference/network-policies) to plan plugin egress rules. +- Follow [Customize Network Policy](../network-policy/customize-network-policy) if the plugin needs a custom preset. diff --git a/docs/deployment/sandbox-hardening.mdx b/docs/deployment/sandbox-hardening.mdx index 32df0db4bd0..dc570c15e44 100644 --- a/docs/deployment/sandbox-hardening.mdx +++ b/docs/deployment/sandbox-hardening.mdx @@ -9,43 +9,35 @@ keywords: ["nemoclaw sandbox hardening", "container security", "docker capabilit content: type: "reference" --- -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. For defense-in-depth, also drop all Linux capabilities at the container runtime when you launch the image directly: @@ -90,7 +82,7 @@ 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 (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 | @@ -110,7 +102,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 diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index 0c7a57e5293..7d90b9d6e4a 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -9,7 +9,7 @@ keywords: ["nemoclaw prerequisites", "nemoclaw supported platforms", "nemoclaw h content: type: "reference" --- -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 @@ -19,7 +19,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 @@ -34,7 +38,7 @@ On Linux, the installer can install Docker, start the Docker service, and add yo 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. - + 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. Members of the `docker` group can control the daemon with root-level impact, so grant this access only to trusted local accounts; on shared or managed systems, use your organization's approved Docker access path. @@ -51,17 +55,17 @@ For NemoClaw-managed environments, use `nemoclaw onboard` when you need to creat 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`. - + 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](../reference/troubleshooting) for the override knobs and a manual `daemon.json` alternative. +You do not need manual setup. +Refer to the [troubleshooting guide](../reference/troubleshooting) 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. {/* platform-matrix:begin */} | OS | Container runtime | Status | Notes | diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index 5e6c4ad44f4..ffc4bcf0847 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -15,7 +15,7 @@ Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs H The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected. Review the [Prerequisites](prerequisites) before starting. -Docker must be installed, running, and reachable from the current shell before Hermes onboarding can build the sandbox image. +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. @@ -109,8 +109,7 @@ 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, see the -[Hermes web dashboard documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard). +For upstream dashboard features, refer to the [Hermes web dashboard documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard). ```text ────────────────────────────────────────────────── @@ -177,7 +176,7 @@ Do not append an OpenClaw `#token=` URL fragment to the Hermes endpoint. ## Open the Optional Dashboard -When `NEMOCLAW_HERMES_DASHBOARD=1` is set during onboarding, NemoClaw starts `hermes dashboard --no-open` inside the sandbox and forwards `http://127.0.0.1:9119/` on the host. +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: diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 93d99c25866..694d368a22a 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -14,7 +14,7 @@ skill: Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent. -Make sure you have completed reviewing the [Prerequisites](prerequisites) before following this guide. +Review the [Prerequisites](prerequisites) before following this guide. @@ -23,7 +23,7 @@ Load them when you want your assistant to walk through installation, inference c Refer to [Agent Skills](../resources/agent-skills). -## Install NemoClaw and Onboard OpenClaw Agent +## 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. @@ -36,7 +36,7 @@ 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 Node.js or the NemoClaw CLI is installed. +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: @@ -44,7 +44,7 @@ In non-TTY contexts, such as CI, an SSH command with piped stdin, or a shell scr curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash ``` -or pass the installer flag through `bash -s`: +Or pass the installer flag through `bash -s`: ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software @@ -64,7 +64,7 @@ If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/. 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. @@ -80,7 +80,7 @@ On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unle 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. @@ -115,7 +115,7 @@ The inference provider prompt presents a numbered list. 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](../inference/inference-options). 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. +A configured blueprint router profile makes the Model Router option appear. Export the API key before launching the installer so the wizard does not have to ask for it. @@ -222,13 +222,14 @@ Respond to the wizard as follows. 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. +Local Ollama does not require an API key. +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. +2. At the `Choose model [1]:` prompt, pick from **Ollama models** if you already installed any. If no local models exist, 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](../inference/use-local-inference). @@ -261,7 +262,7 @@ The sandbox still calls `https://inference.local/v1`, so do not point in-sandbox - **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 (already running)** appears whenever NemoClaw detects a vLLM server on `localhost:8000`. You do not need a flag 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](../inference/use-local-inference). @@ -289,7 +290,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. @@ -319,7 +320,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. @@ -365,7 +366,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. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 9aa4d7df21e..993b7be7b80 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -21,7 +21,7 @@ Complete these steps before following [Quickstart with Hermes](../quickstart-her Linux and macOS users do not need this page and can go directly to the Quickstart. -This guide has been tested on x86-64. +NVIDIA tested this guide on x86-64. ## Prerequisites @@ -70,10 +70,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), make sure Docker Desktop is running, 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. @@ -102,10 +103,10 @@ 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 @@ -122,7 +123,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: @@ -137,7 +138,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) @@ -148,7 +149,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. diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 2a5d27076b7..fe6a1bb780c 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -13,7 +13,7 @@ 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 the agent's inference traffic is routed. +Your selection determines where NemoClaw routes the agent's inference traffic. For OpenClaw onboarding, use `nemoclaw onboard`. @@ -58,7 +58,7 @@ 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. @@ -78,7 +78,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. | @@ -181,12 +181,13 @@ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemohermes 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. @@ -201,20 +202,20 @@ For setup instructions, refer to [Use a Local Inference Server](use-local-infere 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). | ## Next Steps diff --git a/docs/inference/set-up-sub-agent.mdx b/docs/inference/set-up-sub-agent.mdx index b37c2bd1c87..c836365565c 100644 --- a/docs/inference/set-up-sub-agent.mdx +++ b/docs/inference/set-up-sub-agent.mdx @@ -46,7 +46,7 @@ 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 @@ -86,7 +86,7 @@ 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: ```bash docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- chown -R sandbox:sandbox /sandbox/.openclaw/agents/vision-operator diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index 99f7f3389e7..0cf7cb930f6 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -14,7 +14,7 @@ skill: 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 @@ -33,7 +33,7 @@ Use `nemohermes inference set` with the provider and model that match the upstre 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 `nemohermes`, pass `--sandbox ` when more than one Hermes sandbox is registered. +Under `nemohermes`, pass `--sandbox ` when you have registered more than one Hermes sandbox. @@ -129,10 +129,8 @@ nemohermes 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. ```bash @@ -145,13 +143,10 @@ nemohermes 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: ```bash @@ -165,10 +160,8 @@ NEMOCLAW_PREFERRED_API=openai-responses nemohermes onboard -`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. @@ -219,7 +212,7 @@ 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. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. @@ -248,22 +241,19 @@ nemohermes 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_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 (for example, -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 via `nemohermes 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 `nemohermes onboard` to apply a new value. @@ -276,16 +266,14 @@ 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 via `nemohermes onboard --resume` to apply build-time inference -metadata changes. +Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. +Rebuild the sandbox with `nemohermes onboard --resume` to apply build-time inference metadata changes. diff --git a/docs/inference/tool-calling-reliability.mdx b/docs/inference/tool-calling-reliability.mdx index b0c22a9e2a2..653cb920227 100644 --- a/docs/inference/tool-calling-reliability.mdx +++ b/docs/inference/tool-calling-reliability.mdx @@ -4,15 +4,13 @@ title: "Tool-Calling Reliability for Local Inference" sidebar-title: "Tool-Calling Reliability" description: "Diagnose local inference setups where tool calls leak as plain text and choose when to use Ollama or vLLM." -description-agent: "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." +description-agent: "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." keywords: ["nemoclaw tool calling", "ollama tool calls", "vllm tool-call-parser", "raw json in tui"] content: type: "troubleshooting" --- -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: @@ -20,8 +18,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 @@ -35,9 +32,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 @@ -48,15 +44,12 @@ 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: @@ -108,14 +101,12 @@ NEMOCLAW_PROVIDER=custom \ 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: @@ -141,15 +132,13 @@ like this: } ``` -Apply it only in environments where OpenClaw config writes are allowed: +Apply it only in environments where OpenClaw allows config writes: ```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 @@ -157,12 +146,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/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index dcda715c018..fa46c694c60 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -33,13 +33,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. @@ -50,7 +51,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. @@ -61,12 +62,14 @@ 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. @@ -82,7 +85,7 @@ nemohermes 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. @@ -98,8 +101,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`. @@ -125,8 +128,7 @@ tool, switch to vLLM with `--enable-auto-tool-choice` and the correct 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. @@ -161,15 +163,12 @@ nemohermes 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 @@ -202,8 +201,9 @@ If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on availa 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. +`--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 | @@ -406,7 +406,7 @@ NEMOCLAW_PROVIDER=vllm \ ``` -Install or start managed vLLM when a supported profile is detected. +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. @@ -430,7 +430,7 @@ Start vLLM with the model you want before onboarding if you manage the server yo 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: +Recognized slugs are: | Slug | Hugging Face model | Notes | |---|---|---| @@ -440,7 +440,7 @@ Recognised slugs: | `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. +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: @@ -461,7 +461,7 @@ NEMOCLAW_PROVIDER=install-vllm \ ``` -`HUGGING_FACE_HUB_TOKEN` is accepted as an alternative. +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) @@ -485,9 +485,9 @@ 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. +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 once on a bad key before failing. +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`. @@ -542,7 +542,7 @@ nemohermes onboard The value is in seconds. -This setting is baked into the sandbox at build time. +NemoClaw bakes this setting into the sandbox at build time. Changing it after onboarding requires re-running `nemoclaw onboard`. @@ -554,7 +554,8 @@ Changing it after onboarding requires re-running `nemohermes onboard`. 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 — large quantised models, DGX Station first runs, or remote VMs over a slow link — raise both together: +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 diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index 886463b8c58..e2c6c350360 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -39,12 +39,9 @@ This guide covers snapshot commands, manual backup with CLI commands, and an aut 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. +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 @@ -61,7 +58,8 @@ nemohermes 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`: @@ -112,14 +110,14 @@ nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone 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. +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 `nemohermes rebuild` command uses the same snapshot mechanism automatically. -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 @@ -248,27 +246,22 @@ Use manual `openshell sandbox download` / `openshell sandbox upload` only when y ## 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#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#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). @@ -276,9 +269,8 @@ editing, or maintain a host-side sync layer. Tracking shared-file tooling ## 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. See [Workspace Files](workspace-files) for the Hermes -state layout. +NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable top-level files instead. +Refer to [Workspace Files](workspace-files) for the Hermes state layout. diff --git a/docs/manage-sandboxes/install-plugins-hermes.mdx b/docs/manage-sandboxes/install-plugins-hermes.mdx index 0c353a2161c..6ec095d7979 100644 --- a/docs/manage-sandboxes/install-plugins-hermes.mdx +++ b/docs/manage-sandboxes/install-plugins-hermes.mdx @@ -105,8 +105,8 @@ If a plugin calls an external API at runtime, add a policy preset for the requir 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, see [Network Policies](../reference/network-policies). -For custom preset workflows, see [Customize Network Policy](../network-policy/customize-network-policy). +For policy concepts, refer to [Network Policies](../reference/network-policies). +For custom preset workflows, refer to [Customize Network Policy](../network-policy/customize-network-policy). ## Common Mistakes @@ -116,7 +116,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 assume Python package downloads during runtime are allowed by default; sandbox egress still follows OpenShell policy. +- Do not assume OpenShell policy allows Python package downloads during runtime by default. ## Next Steps diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 956e26615c1..aac43a0e9aa 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -42,7 +42,7 @@ nemohermes 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: @@ -268,7 +268,7 @@ Refer to the command reference for details on `nemohermes recover`. ### 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: ```bash @@ -286,10 +286,10 @@ nemohermes onboard # re-run to re-enter the cleared prov -The credentials command is documented in full at [`nemoclaw credentials reset `](../reference/commands#nemoclaw-credentials-reset-provider). +The command reference documents [`nemoclaw credentials reset `](../reference/commands#nemoclaw-credentials-reset-provider) in full. -The credentials command is documented in full in the [Commands reference](../reference/commands). +The [Commands reference](../reference/commands) documents the credentials command in full. ### Rebuild a Sandbox While Preserving Workspace State @@ -350,7 +350,7 @@ When a maintained NemoClaw release becomes available, update the `nemoclaw` CLI When a maintained NemoClaw release becomes available, update the `nemohermes` CLI on your host and check existing sandboxes for stale agent/runtime versions. -The standard installer follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes. +The standard installer follows the admin-promoted `lkg` release tag by default, so it can trail the newest semver or `latest` tag while validation completes. ### Update the NemoClaw CLI @@ -363,12 +363,14 @@ Before it onboards anything, the installer calls `nemohermes backup-all` automat 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`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +The installer offers the automatic path 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`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. -The automatic path is offered only when the existing `nemohermes` 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 `nemohermes backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. +The installer offers the automatic path only when the existing `nemohermes` 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 `nemohermes backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (the command tries both verbs so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. ```bash @@ -383,7 +385,7 @@ The installer checks registered sandboxes after onboarding succeeds and runs `ne The installer checks registered sandboxes after onboarding succeeds and runs `nemohermes 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. +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. @@ -450,7 +452,7 @@ NemoClaw protects your data through the same backup-and-restore flow as `nemoher 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. +The flow refuses to proceed past preflight if a credential is missing or past backup if it cannot copy required manifest-defined state, 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) for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough. @@ -458,14 +460,14 @@ See [Backup and Restore](backup-restore) for the full list of state-preservation 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. +If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight can 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. The rebuild preflight reads the provider credential recorded by your last `nemohermes 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. +If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight can still reference the old key and fail before any destroy step runs. To recover, re-run `nemohermes onboard` and select your current provider. This refreshes the session metadata. @@ -516,7 +518,7 @@ 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`](../reference/commands#nemoclaw-uninstall-vs-the-hosted-uninstallsh). +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`](../reference/commands#nemoclaw-uninstall-vs-the-hosted-uninstallsh). ## Related Topics diff --git a/docs/manage-sandboxes/messaging-channels.mdx b/docs/manage-sandboxes/messaging-channels.mdx index 65e90c5cd29..a5cbba52667 100644 --- a/docs/manage-sandboxes/messaging-channels.mdx +++ b/docs/manage-sandboxes/messaging-channels.mdx @@ -16,13 +16,13 @@ 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. 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. @@ -68,8 +68,8 @@ For details, refer to [Commands](../reference/commands). | 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 | @@ -79,8 +79,8 @@ For details, refer to [Commands](../reference/commands). | 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 `nemohermes 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 `nemohermes onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | +| WhatsApp (experimental) | None. Pair through QR after rebuild | None | @@ -108,7 +108,7 @@ Set `SLACK_ALLOWED_CHANNELS` to comma-separated Slack channel IDs to restrict ch 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. -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. @@ -120,11 +120,11 @@ Because the bot token only exists after a successful iLink QR handshake, NemoCla 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. @@ -140,9 +140,9 @@ 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 once and then check `nemoclaw channels status --channel whatsapp` so you can diagnose the gateway/session path separately from QR rendering. +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. -Session credentials are generated and stored inside durable agent state (`whatsapp` for OpenClaw, `platforms/whatsapp` for Hermes), so they survive rebuilds without re-pairing. +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. @@ -151,7 +151,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 no channels are selected, pressing **Enter** skips messaging setup. +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. @@ -238,13 +238,15 @@ nemohermes 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. `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, but flags `gateway-providers` as residual because the in-flight upsert may have left the gateway with the new token; verify the gateway bridge before relying on the channel. +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 `. @@ -311,7 +313,7 @@ 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`. @@ -364,9 +366,10 @@ 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: diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx index a6b709ba2c9..ca72cdce82e 100644 --- a/docs/manage-sandboxes/runtime-controls.mdx +++ b/docs/manage-sandboxes/runtime-controls.mdx @@ -15,30 +15,30 @@ 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) | +| 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. @@ -49,13 +49,13 @@ If a row above conflicts with what you observe, the runtime source of truth insi |---|---|---| | 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 | `nemohermes inference set` for route changes, or `nemohermes rebuild` after changing build-time settings | | Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemohermes inference set` | -| Agent runtime (Hermes vs OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemohermes 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 | `nemohermes 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 | +| Agent runtime (Hermes compared to OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemohermes 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 | `nemohermes 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) | `nemohermes 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) | `nemohermes channels stop ` then rebuild | -| API/dashboard forward port | Runtime — port is re-resolved on next `connect` | `nemohermes connect` or `openshell forward start` | -| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation** — no runtime change | Re-onboard with `nemohermes onboard --recreate-sandbox` | +| API/dashboard forward port | Runtime. Port is re-resolved on next `connect` | `nemohermes connect` or `openshell forward start` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `nemohermes 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 `nemohermes inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | @@ -67,26 +67,26 @@ 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](lifecycle) — full rebuild / re-onboard / upgrade workflow. -- [Switch Inference Providers](../inference/switch-inference-providers) — the rebuild path for provider and model changes. -- [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) — runtime policy editing and operator approval flow. -- [Security Best Practices](../security/best-practices) — the per-attack-surface posture table that this page complements. -- [OpenClaw Security Controls](../security/openclaw-controls) — application-layer controls that operate independently of NemoClaw. -- [CLI Commands Reference](../reference/commands) — full flag surface for every `nemoclaw` command, including the env vars that affect runtime behavior. +- [Manage Sandbox Lifecycle](lifecycle) for the full rebuild, re-onboard, and upgrade workflow. +- [Switch Inference Providers](../inference/switch-inference-providers) for the rebuild path for provider and model changes. +- [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) for runtime policy editing and operator approval flow. +- [Security Best Practices](../security/best-practices) for the per-attack-surface posture table that this page complements. +- [OpenClaw Security Controls](../security/openclaw-controls) for application-layer controls that operate independently of NemoClaw. +- [CLI Commands Reference](../reference/commands) for the full flag surface for every `nemoclaw` command, including the environment variables that affect runtime behavior. -- [Manage Sandbox Lifecycle](lifecycle) — full rebuild / re-onboard / upgrade workflow. -- [Switch Inference Providers](../inference/switch-inference-providers) — the runtime route and rebuild paths for provider and model changes. -- [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) — runtime policy editing and operator approval flow. -- [Security Best Practices](../security/best-practices) — the per-attack-surface posture table that this page complements. -- [CLI Commands Reference](../reference/commands) — full flag surface for every `nemohermes` and `nemoclaw` command, including the env vars that affect runtime behavior. +- [Manage Sandbox Lifecycle](lifecycle) for the full rebuild, re-onboard, and upgrade workflow. +- [Switch Inference Providers](../inference/switch-inference-providers) for the runtime route and rebuild paths for provider and model changes. +- [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) for runtime policy editing and operator approval flow. +- [Security Best Practices](../security/best-practices) for the per-attack-surface posture table that this page complements. +- [CLI Commands Reference](../reference/commands) for the full flag surface for every `nemohermes` and `nemoclaw` command, including the environment variables that affect runtime behavior. diff --git a/docs/manage-sandboxes/workspace-files.mdx b/docs/manage-sandboxes/workspace-files.mdx index 4e19253f737..55bef895c1e 100644 --- a/docs/manage-sandboxes/workspace-files.mdx +++ b/docs/manage-sandboxes/workspace-files.mdx @@ -22,7 +22,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. | @@ -46,7 +46,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/`: @@ -60,27 +60,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/`. 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 @@ -94,7 +90,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. Back up your workspace files before running `nemoclaw destroy`. diff --git a/docs/monitoring/monitor-sandbox-activity.mdx b/docs/monitoring/monitor-sandbox-activity.mdx index c44444fd8c3..b5db364928c 100644 --- a/docs/monitoring/monitor-sandbox-activity.mdx +++ b/docs/monitoring/monitor-sandbox-activity.mdx @@ -41,14 +41,14 @@ For local Ollama and local vLLM routes, `nemoclaw status` also probes the For local Ollama and local vLLM routes, `nemohermes 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. diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx index 55ecd34e1f3..07452657a2c 100644 --- a/docs/network-policy/customize-network-policy.mdx +++ b/docs/network-policy/customize-network-policy.mdx @@ -13,9 +13,9 @@ skill: --- import { AgentOnly } from "../_components/AgentGuide"; -Add, remove, or modify the endpoints that the sandbox is allowed to reach. +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. @@ -38,7 +38,7 @@ See [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#a > [!IMPORTANT] > Make static policy edits on the host, not inside the sandbox. > The sandbox image includes a small set of operational tools such as `vi`, `jq`, and `dos2unix`, but host-side policy files remain the durable source of truth. -> Changes made only inside the sandbox are also ephemeral and are lost when the sandbox is recreated. +> The sandbox also loses changes made only inside the sandbox when it is recreated. ## Static Changes @@ -91,7 +91,7 @@ nemohermes 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 @@ -169,7 +169,7 @@ NemoClaw reads the live policy via `openshell policy get --full`, structurally m 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 a baseline policy file, so the presets layered on at onboarding are preserved in the file you apply. @@ -189,10 +189,10 @@ openshell policy set --policy live-policy.yaml my-assistant Dynamic changes apply only to the current session. When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox. -To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above — the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. +To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above; the file under `presets/` persists) or edit `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 `nemohermes 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 `nemohermes onboard`. ### Approve Requests Interactively @@ -286,8 +286,7 @@ To include a preset in the baseline, merge its entries into the Hermes policy ad -The `openshell policy set --policy ` command operates on raw policy files and does not -accept the `preset:` metadata block used in preset YAML files. +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. @@ -389,7 +388,8 @@ Review every host in a custom preset before applying it, especially when the fil ### 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: +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 diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 5676e66d6c6..eb4eb6172cf 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -13,12 +13,6 @@ skill: --- import { AgentOnly } from "../_components/AgentGuide"; - -{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */} -{/* SPDX-License-Identifier: Apache-2.0 */} - -# Common NemoClaw Integration Policy Examples - 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: @@ -54,7 +48,7 @@ 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 @@ -249,7 +243,8 @@ nemohermes 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. @@ -270,7 +265,7 @@ nemohermes 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: @@ -467,7 +462,7 @@ You do not need to bootstrap Homebrew, install build dependencies, or source `br -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. @@ -480,7 +475,7 @@ 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. diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index c543951fdce..6a9d356ef23 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -235,7 +235,9 @@ On the Docker-driver gateway path, preflight stays read-only when it detects a s It prints a `⚠ Gateway will be recreated when sandbox creation starts` notice and defers the actual teardown to step `[2/8] Starting OpenShell gateway`. This means pressing `Ctrl+C` between preflight and step `[2/8]` leaves the running gateway and existing sandbox containers untouched, so `nemohermes onboard` is safe to run just to check preflight output. For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach `host.openshell.internal:`. -If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to any port proto tcp` command before it reports the gateway healthy. +If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to port proto tcp` command before it reports the gateway healthy. +Set `NEMOCLAW_AUTO_FIX_FIREWALL=1` to opt in to automatic UFW remediation for this specific failure: NemoClaw uses `sudo -n` only, validates the Docker bridge subnet/gateway/port, applies the narrow UFW rule only after a proven TCP reachability failure, and re-probes before continuing. +If passwordless sudo, UFW, or active UFW is unavailable, NemoClaw falls back to the manual guidance path without prompting for a password. Tune the wait via `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds). The poll count is clamped to a minimum of `1` so the probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). @@ -846,6 +848,90 @@ nemohermes my-assistant skill remove my-skill Use the skill name from the `SKILL.md` frontmatter, not the local directory name. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores, and cannot be `.` or `..`. +### `nemohermes agents add` + +Run the OpenClaw interactive add wizard inside the sandbox. +This is a thin pass-through to `openclaw agents add` via `openshell sandbox exec`; flags accepted by the in-sandbox CLI are forwarded verbatim. + +```bash +nemohermes my-assistant agents add +nemohermes my-assistant agents add work --model gpt-4o +``` + +### `nemohermes agents delete ` + +Remove an OpenClaw agent from the sandbox. +This is a thin pass-through to `openclaw agents delete ` via `openshell sandbox exec`; the OpenClaw CLI owns gateway dispatch (`agents.delete`), host-side workspace removal, and config edits. +Flags accepted by the in-sandbox CLI (`--force`, `--json`) are forwarded verbatim. + +```bash +nemohermes my-assistant agents delete work +nemohermes my-assistant agents delete work --force --json +``` + +### `nemohermes sessions` + +List OpenClaw conversation sessions in the sandbox. +With no subcommand the in-sandbox CLI lists stored sessions for the configured default agent. +This is a thin pass-through to `openclaw sessions` via `openshell sandbox exec`; flags accepted by the in-sandbox CLI are forwarded verbatim. + +```bash +nemohermes my-assistant sessions +nemohermes my-assistant sessions --all-agents --json +``` + +### `nemohermes sessions list` + +Pass-through to `openclaw sessions list` inside the sandbox. +Accepts every flag the in-sandbox CLI does (`--agent`, `--all-agents`, `--active`, `--limit`, `--json`, `--store`, `--verbose`). + +```bash +nemohermes my-assistant sessions list +nemohermes my-assistant sessions list --agent work --json +``` + +### `nemohermes sessions reset ` + +Archive a session and rebind its key to a fresh `sessionId` by invoking the OpenClaw gateway `sessions.reset` RPC inside the sandbox. +Goes through `openshell sandbox exec` -> `openclaw gateway call sessions.reset`, so the gateway owns archival, lock handling, and lifecycle events; the host never edits `sessions.json` directly. + +```bash +nemohermes my-assistant sessions reset main +nemohermes my-assistant sessions reset agent:work:telegram:t-1 +nemohermes my-assistant sessions reset telegram:t-1 --agent work --reason new +nemohermes my-assistant sessions reset agent:main:main --json +``` + +| Flag | Description | +|------|-------------| +| `--agent ` | Agent id when `` is an alias rather than the canonical `agent::` form. | +| `--reason new\|reset` | `reset` (default) archives the prior transcript; `new` rebinds without preserving the archive trail. | +| `--json` | Print the reset result as JSON. | +| `--verbose` | Print the gateway entry payload after a successful reset. | + +The `` argument accepts an alias (e.g. `main`, `telegram:t-1`) or the canonical `agent::` form. +Mismatched `--agent` plus canonical-key combinations are refused before the gateway is invoked. + +### `nemohermes sessions delete ` + +Remove a session entry by invoking the OpenClaw gateway `sessions.delete` RPC inside the sandbox. +The gateway refuses to remove the agent's main session. +The transcript on disk is removed by default; pass `--keep-transcript` to retain it. + +```bash +nemohermes my-assistant sessions delete telegram:t-1 +nemohermes my-assistant sessions delete agent:work:telegram:t-1 +nemohermes my-assistant sessions delete telegram:t-1 --agent work --keep-transcript +nemohermes my-assistant sessions delete agent:main:slack:c-9 --json +``` + +| Flag | Description | +|------|-------------| +| `--agent ` | Agent id when `` is an alias rather than the canonical `agent::` form. | +| `--keep-transcript` | Retain the session transcript on disk after the entry is removed. | +| `--json` | Print the delete result as JSON. | +| `--verbose` | Print the gateway entry payload after a successful delete. | + ### `nemohermes rebuild` Upgrade a sandbox to the current agent version while preserving workspace state. @@ -1472,6 +1558,7 @@ These flags toggle optional behaviors during onboarding; set them before running | `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. | ### Onboard Profiling Traces diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx index cbfd8fe18e7..3254af2b381 100644 --- a/docs/security/best-practices.mdx +++ b/docs/security/best-practices.mdx @@ -13,7 +13,7 @@ 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](../about/how-it-works). @@ -27,7 +27,7 @@ For the full platform-level controls reference, see [OpenShell Security Best Pra ## 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 onboarding, before you approve any endpoints or apply any presets. @@ -111,7 +111,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 | |---|---| @@ -145,7 +145,7 @@ 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 | |---|---| @@ -205,7 +205,7 @@ 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 high-risk 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`. @@ -215,7 +215,7 @@ The list is the union of state directories declared by every shipped agent manif 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, it refuses to proceed and reports "Config not locked: state dir root is a symlink" rather than silently following the link with privileged `chown -R` / `chmod -R`. +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. @@ -291,7 +291,7 @@ 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](../manage-sandboxes/sandbox-hardening)). @@ -328,7 +328,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 | |---|---| @@ -522,7 +522,9 @@ 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 | |---|---| diff --git a/docs/security/credential-storage.mdx b/docs/security/credential-storage.mdx index 9f871899140..53e0b2b3dd0 100644 --- a/docs/security/credential-storage.mdx +++ b/docs/security/credential-storage.mdx @@ -15,10 +15,10 @@ 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`. -When you provide a provider credential — interactively during `nemohermes 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 `nemohermes 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. @@ -51,7 +51,8 @@ nemohermes 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. @@ -98,7 +99,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. diff --git a/docs/security/openclaw-controls.mdx b/docs/security/openclaw-controls.mdx index 0ebbcf98683..5c4bc1fce56 100644 --- a/docs/security/openclaw-controls.mdx +++ b/docs/security/openclaw-controls.mdx @@ -65,7 +65,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: @@ -101,7 +101,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 | @@ -119,7 +119,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/fern/fern.config.json b/fern/fern.config.json index b813bcb86e3..5495dca9a78 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "nvidia", - "version": "5.41.2" + "version": "5.44.3" }