diff --git a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md index 77e24a1bf6..65af07602b 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/SKILL.md +++ b/.agents/skills/nemoclaw-user-configure-inference/SKILL.md @@ -28,6 +28,9 @@ The onboard wizard detects Ollama automatically when it is installed or running If Ollama is installed but not running, NemoClaw starts it for you. On macOS and Linux, the wizard can also offer to install Ollama when it is not present. On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop. +On Debian and Ubuntu, the native Linux install path checks for `zstd` before it runs the Ollama installer. +If `zstd` is missing, NemoClaw installs it with `apt-get` and explains the sudo prompt before continuing. +On non-apt Linux distributions, install `zstd` first, then rerun onboarding. Run the onboard wizard. @@ -85,9 +88,10 @@ 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. -`GET /api/tags` is exempt from authentication so container health checks -continue to work. -All other endpoints (including `POST /api/tags`) require the Bearer token. +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. 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 @@ -218,15 +222,14 @@ $ NEMOCLAW_PROVIDER=anthropicCompatible \ When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. -Set the experimental flag and run onboard. +For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. ```console -$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard +$ nemoclaw onboard ``` -Select **Local vLLM [experimental]** from the provider list. If vLLM is already running, NemoClaw detects the running model and validates the endpoint. -If vLLM is not running and your host matches a managed profile, select the **Install vLLM** or **Start vLLM** entry. +If vLLM is not running and your host matches a managed profile, set `NEMOCLAW_EXPERIMENTAL=1`, rerun `nemoclaw onboard`, and select the **Install vLLM** or **Start vLLM** entry. NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, and prints progress markers while the model loads. The first run can take 10 to 30 minutes. Later runs reuse the cached image and model weights. @@ -247,8 +250,7 @@ Managed vLLM uses these profiles: Use an already-running vLLM server: ```console -$ NEMOCLAW_EXPERIMENTAL=1 \ - NEMOCLAW_PROVIDER=vllm \ +$ NEMOCLAW_PROVIDER=vllm \ nemoclaw onboard --non-interactive ``` diff --git a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md index 72b83328d4..a6b08fa5f3 100644 --- a/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md +++ b/.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md @@ -31,7 +31,7 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l | Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` | | Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host | | Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU | -| Local vLLM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a server already running on `localhost:8000` | +| Local vLLM | Experimental | Local OpenAI-compatible | Appears when a vLLM server is already running on `localhost:8000`; managed install/start requires `NEMOCLAW_EXPERIMENTAL=1` | ## Provider Options @@ -39,7 +39,8 @@ 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. -Experimental local vLLM appears when you opt in and NemoClaw detects either a running vLLM server or a supported NVIDIA GPU host profile. +Experimental local vLLM appears when NemoClaw detects a running vLLM server. +The managed install/start vLLM entry appears when you opt in and NemoClaw detects a supported NVIDIA GPU host profile. | Option | Description | Curated models | |--------|-------------|----------------| @@ -83,12 +84,13 @@ $ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-inte ## Experimental Options -The following local inference options require `NEMOCLAW_EXPERIMENTAL=1` and, when prerequisites are met, appear in the onboarding selection list. +The following local inference options are experimental. +Local NIM and managed vLLM install/start require `NEMOCLAW_EXPERIMENTAL=1`; an already-running vLLM server appears directly in the onboarding selection list. | Option | Condition | Notes | |--------|-----------|-------| | Local NVIDIA NIM | NIM-capable GPU detected | Pulls and manages a NIM container. | -| Local vLLM | vLLM running on `localhost:8000`, or a supported DGX Spark, DGX Station, or Linux NVIDIA GPU profile | Auto-detects the loaded model. Can install or start a managed vLLM container for supported profiles. | +| Local vLLM | vLLM running on `localhost:8000`, or a supported DGX Spark, DGX Station, or Linux NVIDIA GPU profile | Auto-detects the loaded model when vLLM is already running. Can install or start a managed vLLM container for supported profiles after experimental opt-in. | For setup instructions, refer to Use a Local Inference Server (use the `nemoclaw-user-configure-inference` skill). diff --git a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md index 5bb00f69f6..25baea156a 100644 --- a/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md +++ b/.agents/skills/nemoclaw-user-configure-security/references/best-practices.md @@ -230,21 +230,6 @@ For sensitive workloads, use a reviewed host-side immutability workflow after in | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | | Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | -### Locking Config with Shields - -NemoClaw exposes the reviewed host-side immutability workflow through shields commands: - -| Command | Purpose | -|---|---| -| `nemoclaw shields status` | Show whether the sandbox is in default mutable mode, locked mode, or temporarily unlocked mode. | -| `nemoclaw shields up` | Opt into lockdown for sensitive workloads by locking config and state entry points with root ownership, read-only modes, and the immutable flag where available. | -| `nemoclaw shields down --timeout 5m --reason ""` | Temporarily return a previously locked sandbox to the mutable default for maintenance, then auto-restore lockdown. | - -Run shields commands from the host. -They use privileged OpenShell and Kubernetes paths that do not inherit the sandbox process's Landlock context. -Landlock itself stays fixed at sandbox creation; `shields up` does not rewrite the Landlock policy. -Instead, it layers DAC permissions and `chattr +i` over paths that the default Landlock policy intentionally leaves writable. - ### Writable Paths The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`. diff --git a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md index f7b7a89b50..2e491e0181 100644 --- a/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md +++ b/.agents/skills/nemoclaw-user-deploy-remote/references/sandbox-hardening.md @@ -91,8 +91,6 @@ The agent's home directory (`/sandbox`) is writable by default: This writable default is intentional. Seeing the sandbox user create files under `/sandbox` or `/sandbox/.openclaw` in a fresh sandbox does not mean Landlock failed. Landlock still enforces the fixed read-only system paths below. -Use `nemoclaw shields up` from the host to opt into config lockdown for sensitive workloads. -That host-side command layers root ownership, read-only modes, and the immutable flag where available; it does not change the Landlock policy after sandbox creation. System paths remain read-only to prevent agents from: diff --git a/.agents/skills/nemoclaw-user-get-started/SKILL.md b/.agents/skills/nemoclaw-user-get-started/SKILL.md index dd9424b7c3..09044c33e2 100644 --- a/.agents/skills/nemoclaw-user-get-started/SKILL.md +++ b/.agents/skills/nemoclaw-user-get-started/SKILL.md @@ -272,7 +272,7 @@ For example, Slack bot tokens must start with `xoxb-`. ### Choose Network Policy Presets After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. @@ -346,9 +346,4 @@ openclaw agent --agent main --local -m "hello" --session-id test ## Related Skills -- `nemoclaw-user-manage-sandboxes` — Manage NemoClaw sandboxes (use the `nemoclaw-user-manage-sandboxes` skill) for port forwards, rebuilds, upgrades, and uninstall -- `nemoclaw-user-configure-inference` — Switch inference providers (use the `nemoclaw-user-configure-inference` skill) to use a different model or endpoint -- `nemoclaw-user-manage-policy` — Approve or deny network requests (use the `nemoclaw-user-manage-policy` skill) when the agent tries to reach external hosts -- `nemoclaw-user-deploy-remote` — Deploy to a remote GPU instance (use the `nemoclaw-user-deploy-remote` skill) for always-on operation -- `nemoclaw-user-monitor-sandbox` — Monitor sandbox activity (use the `nemoclaw-user-monitor-sandbox` skill) through the OpenShell TUI -- `nemoclaw-user-reference` — Consult the troubleshooting guide (use the `nemoclaw-user-reference` skill) for common error messages and resolution steps +- `nemoclaw-user-overview` — NemoClaw Overview (use the `nemoclaw-user-overview` skill) to learn what NemoClaw is and its capabilities diff --git a/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md b/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md index 7083f12d9c..30e2f3d7a7 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md +++ b/.agents/skills/nemoclaw-user-get-started/references/prerequisites.md @@ -25,6 +25,8 @@ The sandbox image is approximately 2.4 GB compressed. During image push, the Doc On Linux, the installer can install Docker, start the Docker service, and add your user to the `docker` group. If the group change is not active in the current shell, the installer exits with `newgrp docker` guidance before it starts onboarding. +If you choose the native Linux Ollama install path, the onboard wizard also requires `zstd` for Ollama archive extraction. +On Debian and Ubuntu, NemoClaw installs `zstd` with `apt-get` if it is missing; on other Linux distributions, install `zstd` before onboarding. :::{warning} OpenShell Lifecycle For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. diff --git a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md index 92825af90e..98071a436d 100644 --- a/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md +++ b/.agents/skills/nemoclaw-user-get-started/references/quickstart-hermes.md @@ -5,7 +5,7 @@ Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent. The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected. -> **Warning:** The Hermes agent option is experimental. +> **Experimental Feature:** The Hermes agent option is experimental. > Interfaces, defaults, and supported features may change without notice, and it is not recommended for production use. Review the Prerequisites (use the `nemoclaw-user-get-started` skill) before starting. diff --git a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md index fd397154b5..fc27016cb5 100644 --- a/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md +++ b/.agents/skills/nemoclaw-user-manage-sandboxes/SKILL.md @@ -184,6 +184,9 @@ When a new NemoClaw release becomes available, update the `nemoclaw` CLI on your Re-run the installer. Before it onboards anything, the installer calls `nemoclaw backup-all` (use the `nemoclaw-user-reference` skill) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. +If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path. +The automatic path is offered only when the existing `nemoclaw` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway. +For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all` and `openshell gateway destroy -g nemoclaw || openshell gateway destroy` before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. ```console $ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash diff --git a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md index 2d7505f599..1fc6ea0025 100644 --- a/.agents/skills/nemoclaw-user-overview/references/ecosystem.md +++ b/.agents/skills/nemoclaw-user-overview/references/ecosystem.md @@ -8,18 +8,8 @@ This page describes how the ecosystem is formed across projects, where NemoClaw ## How the Stack Fits Together -Three pieces usually appear together in a NemoClaw deployment, each with a distinct scope: - -| Project | Scope | -|---------|--------| -| [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. | -| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | -| NemoClaw | The NVIDIA reference stack that implements the definition above on the host: `nemoclaw` CLI and plugin, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so OpenClaw runs inside OpenShell in a documented, repeatable way. | - -NemoClaw sits above OpenShell in the operator workflow. -It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw. -Models and endpoints sit behind OpenShell's inference routing. -NemoClaw onboarding wires provider choice into that routing. +There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope. +The following diagram shows how they fit together. ```mermaid flowchart TB @@ -42,6 +32,19 @@ flowchart TB linkStyle 1 stroke:#76b900,stroke-width:2px ``` +NemoClaw sits above OpenShell in the operator workflow. +It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw. +Models and endpoints sit behind OpenShell's inference routing. +NemoClaw onboarding wires provider choice into that routing. + +The following table shows the scope of each component in the stack. + +| Project | Scope | +|---------|--------| +| [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. | +| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | +| NemoClaw | The NVIDIA reference stack that implements the definition above on the host: `nemoclaw` CLI and plugin, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so OpenClaw runs inside OpenShell in a documented, repeatable way. | + ## NemoClaw Path versus OpenShell Path Both paths assume OpenShell can sandbox a workload. diff --git a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md index b4e9cc2e4e..6e3571ce06 100644 --- a/.agents/skills/nemoclaw-user-overview/references/how-it-works.md +++ b/.agents/skills/nemoclaw-user-overview/references/how-it-works.md @@ -1,70 +1,47 @@ -# How NemoClaw Works +# NemoClaw Architecture Overview -This page explains how NemoClaw operates, which parts run where, how the blueprint drives OpenShell, and how inference and policy attach to the sandbox. +This page explains how NemoClaw runs OpenClaw inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. -## How the Pieces Connect +NemoClaw does not replace OpenClaw or OpenShell. +It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, plugin configuration, and state helpers. +You can use that setup directly or adapt it for your own OpenShell integration. -The `nemoclaw` CLI is the primary entrypoint for setting up and managing sandboxed OpenClaw agents. -It delegates heavy lifting to a versioned blueprint, a Python artifact that orchestrates sandbox creation, policy application, and inference provider setup through the OpenShell CLI. +## High-Level Flow -Between your shell and the running sandbox, NemoClaw contributes these integration layers: +NemoClaw keeps the user workflow on the host while OpenShell enforces the sandbox boundary. +The gateway sits between NemoClaw control, the sandbox, inference providers, and external integrations. +That placement lets NemoClaw configure the environment without giving the agent direct access to host credentials or uncontrolled network egress. -| Layer | Role in the flow | +```{figure} images/nemoclaw-highlevel-component-diagram.png +:alt: NemoClaw High-Level Component Diagram +:width: 100% +:align: center + +NemoClaw High-Level Component Diagram +``` + +The diagram has the following components: + +| Component | Role in the flow | |-------|------------------| -| Onboarding | `nemoclaw onboard` validates credentials, selects providers, and drives blueprint execution until the sandbox is ready. | -| Blueprint | Supplies the hardened image definition, default policies, capability posture, and orchestration steps the runner applies through OpenShell. | -| State management | Migrates agent state across machines with credential stripping and integrity checks. | -| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the agent. NemoClaw enables this through onboarding and blueprint wiring; delivery is not a separate NemoClaw host daemon. | +| Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. | +| NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. | +| OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. | +| NemoClaw sandbox | Runs OpenClaw with the NemoClaw plugin, the selected blueprint contents, and supporting tools. | +| Inference | Receives model requests through the gateway, using NVIDIA endpoints, NIM, or compatible APIs. | +| Integrations | Reach messaging services, MCP servers, GitHub, package indexes, or model hubs through gateway-managed egress. | +| State and artifacts | Store configuration, credentials, logs, workspace files, policies, and transcripts outside the running agent process. | For repository layout, file paths, and deeper diagrams, see Architecture (use the `nemoclaw-user-reference` skill). -```mermaid -flowchart TB - subgraph Host - CMD["nemoclaw onboard"] - PLUGIN[nemoclaw plugin] - BLUEPRINT[blueprint runner] - CLI["openshell CLI sandbox · gateway · inference · policy"] - - CMD --> PLUGIN - PLUGIN --> BLUEPRINT - BLUEPRINT --> CLI - end - - subgraph Sandbox["OpenShell Sandbox"] - AGENT[OpenClaw agent] - INF[NVIDIA inference, routed] - NET[default network policy] - FS[filesystem isolation] - - AGENT --- INF - AGENT --- NET - AGENT --- FS - end - - PLUGIN --> AGENT - - classDef nv fill:#76b900,stroke:#333,color:#fff - classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a - classDef nvDark fill:#333,stroke:#76b900,color:#fff - - class CMD,PLUGIN,BLUEPRINT nvDark - class CLI nv - class AGENT nv - class INF,NET,FS nvLight - - style Host fill:none,stroke:#76b900,stroke-width:2px,color:#1a1a1a - style Sandbox fill:#f5faed,stroke:#76b900,stroke-width:2px,color:#1a1a1a -``` - ## Design Principles NemoClaw architecture follows the following principles. Thin plugin, versioned blueprint -: The plugin stays small and stable. Orchestration logic lives in the blueprint and evolves on its own release cadence. +: The sandbox plugin stays small and stable. Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. Respect CLI boundaries : The `nemoclaw` CLI is the primary interface for sandbox management. @@ -79,25 +56,26 @@ OpenShell-backed lifecycle Reproducible setup : Running setup again recreates the sandbox from the same blueprint and policy definitions. -## Plugin and Blueprint +## CLI, Plugin, and Blueprint -NemoClaw is split into two parts: +NemoClaw is split into three integration pieces: -- The *plugin* is a TypeScript package that registers an inference provider and the `/nemoclaw` slash command inside the sandbox. - It handles user interaction and delegates orchestration work to the blueprint. -- The *blueprint* is a versioned Python artifact that contains all the logic for creating sandboxes, applying policies, and configuring inference. - The plugin resolves, verifies, and executes the blueprint as a subprocess. +- The *host CLI* runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations. +- The *plugin* is a TypeScript package that runs with OpenClaw inside the sandbox. + It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. +- The *blueprint* is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets. + The runner resolves and verifies the blueprint before applying it through OpenShell. -This separation keeps the plugin small and stable while allowing the blueprint to evolve on its own release cadence. +This separation keeps the sandbox plugin small while allowing host orchestration and blueprint contents to evolve on their own release cadence. ## Sandbox Creation When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container. -The blueprint orchestrates this process through the OpenShell CLI: +The host CLI and blueprint runner orchestrate this process through the OpenShell CLI: -1. The plugin downloads the blueprint artifact, checks version compatibility, and verifies the digest. -2. The blueprint determines which OpenShell resources to create or update, such as the gateway, inference providers, sandbox, and network policy. -3. The blueprint calls OpenShell CLI commands to create the sandbox and configure each resource. +1. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest. +2. The onboarding flow determines which OpenShell resources to create or update, such as the gateway, inference providers, sandbox, and network policy. +3. The runner calls OpenShell CLI commands to create the sandbox and configure each resource. After the sandbox starts, the agent runs inside it with all network, filesystem, and inference controls in place. diff --git a/.agents/skills/nemoclaw-user-overview/references/overview.md b/.agents/skills/nemoclaw-user-overview/references/overview.md index 087384fa79..330cc0c740 100644 --- a/.agents/skills/nemoclaw-user-overview/references/overview.md +++ b/.agents/skills/nemoclaw-user-overview/references/overview.md @@ -1,13 +1,13 @@ -# Overview +# Overview of NVIDIA NemoClaw -NVIDIA NemoClaw is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants. +NVIDIA NemoClaw is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants more safely. NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. It incorporates policy-based privacy and security guardrails, giving you control over your agents’ behavior and data handling. This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. -NemoClaw pairs open-source and hosted models (for example [NVIDIA Nemotron](https://build.nvidia.com)) with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. +NemoClaw pairs hosted models on inference providers or local endpoints with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell); NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run OpenClaw there. | Capability | Description | @@ -25,17 +25,15 @@ NemoClaw provides the following product capabilities. | Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. | | Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. | | State management | Safe migration of agent state across machines with credential stripping and integrity verification. | -| Channel messaging | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | +| Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | | Routed inference | Provider-routed model calls through the OpenShell gateway, transparent to the agent. Supports NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, compatible endpoints, local Ollama, local vLLM, and the Model Router. | | Layered protection | Network, filesystem, process, and inference controls that can be hot-reloaded or locked at creation. | -## Challenge +## Benefits of Using NemoClaw -Autonomous AI agents like OpenClaw can make arbitrary network requests, access the host filesystem, and call any inference endpoint. Without guardrails, this creates security, cost, and compliance risks that grow as agents run unattended. +Autonomous AI agents can make arbitrary network requests, access the host filesystem, and call any inference endpoint. Without guardrails, this creates security, cost, and compliance risks that grow as agents run unattended. -## Benefits - -NemoClaw provides the following benefits. +NemoClaw provides the following benefits to mitigate these risks. | Benefit | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------| @@ -57,10 +55,9 @@ You can use NemoClaw for various use cases including the following. ## Next Steps +Navigate to the following topics to learn more about NemoClaw and how to install and use it. + +- Architecture Overview (use the `nemoclaw-user-overview` skill) to understand how NemoClaw works. - Ecosystem (use the `nemoclaw-user-overview` skill) to understand how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- How It Works (use the `nemoclaw-user-overview` skill) to understand how NemoClaw works internally: plugin, blueprint, sandbox lifecycle. -- Quickstart (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first agent. -- Switch Inference Providers (use the `nemoclaw-user-configure-inference` skill) to configure the inference provider. -- Approve or Deny Network Requests (use the `nemoclaw-user-manage-policy` skill) to manage egress approvals. -- Deploy to a Remote GPU Instance (use the `nemoclaw-user-deploy-remote` skill) for persistent operation. -- Monitor Sandbox Activity (use the `nemoclaw-user-monitor-sandbox` skill) to observe agent behavior. +- Quickstart (use the `nemoclaw-user-get-started` skill) to install NemoClaw and run your first sandboxed agent. +- Inference Options (use the `nemoclaw-user-configure-inference` skill) to check the inference providers that NemoClaw supports and how inference routing works. diff --git a/.agents/skills/nemoclaw-user-overview/references/release-notes.md b/.agents/skills/nemoclaw-user-overview/references/release-notes.md index c3e0fc008d..95364f406f 100644 --- a/.agents/skills/nemoclaw-user-overview/references/release-notes.md +++ b/.agents/skills/nemoclaw-user-overview/references/release-notes.md @@ -2,18 +2,23 @@ # Release Notes -NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use the following GitHub resources to track changes. +NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track changes. -| Resource | Description | -|---|---| -| [Releases](https://github.com/NVIDIA/NemoClaw/releases) | Versioned release notes and downloadable assets. | -| [Release comparison](https://github.com/NVIDIA/NemoClaw/compare) | Diff between any two tags or branches. | -| [Merged pull requests](https://github.com/NVIDIA/NemoClaw/pulls?q=is%3Apr+is%3Amerged) | Individual changes with review discussion. | -| [Commit history](https://github.com/NVIDIA/NemoClaw/commits/main) | Full commit log on `main`. | +## v0.0.40 -## Behavior Changes +NemoClaw v0.0.40 improves onboarding reliability, local inference setup, and sandbox recovery: -### v0.0.39 Release Prep Updates +- `nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS with OpenShell 0.0.37, repairs incomplete Docker-driver installs before startup, and installs the platform-specific gateway asset it needs. +- The Docker-driver gateway startup check waits for the gateway port to accept TCP connections before it reports the gateway as healthy, and startup failures now include child process exit details. +- Local Ollama setup requires the authenticated reverse proxy token on every native Ollama API route, including `GET /api/tags`. +- The Linux Ollama install path preflights `zstd` before running the official installer and explains why each sudo-backed setup step needs elevated privileges. +- The onboarding provider menu offers an already-running local vLLM server directly when `localhost:8000` responds, while managed vLLM install and start options remain behind the experimental opt-in. +- Policy tier defaults are filtered by active agent support, so presets such as Brave Search are not reapplied to agents that do not support that integration. +- `nemoclaw connect` checks dashboard forward reachability with a TCP probe before it reports a forward as stale. +- Sandbox startup captures a known-good OpenClaw config baseline and restores it on restart if `/sandbox/.openclaw/openclaw.json` becomes empty. +- The NemoClaw OpenClaw plugin package declares compatibility metadata for OpenClaw package tooling. + +## v0.0.39 NemoClaw v0.0.39 improves several day-two workflows: @@ -31,7 +36,7 @@ NemoClaw v0.0.39 improves several day-two workflows: - OpenClaw workspace template files are seeded when bootstrap is skipped and the workspace is still empty. - Kimi K2.6 and related NVIDIA-hosted chat-completions paths include model-specific compatibility handling for reasoning output. -### v0.0.38 Reliability Updates +## v0.0.38 NemoClaw v0.0.38 improves several day-two workflows: @@ -42,7 +47,7 @@ NemoClaw v0.0.38 improves several day-two workflows: - Rebuild backups tolerate partial archive output when usable data was produced, then report only the manifest-defined paths that could not be archived. - NemoHermes uninstall output uses NemoHermes-specific help, progress, and completion text. -### v0.0.34 Installer Requires Explicit Acceptance in Non-TTY Environments +## v0.0.34 Starting with NemoClaw v0.0.34, the `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash` installer pipeline no longer auto-accepts the third-party software notice when stdin is piped and `/dev/tty` is unavailable (for example, deeply detached SSH sessions or some container shells). In environments without a TTY, accept upfront in the pipe: diff --git a/.agents/skills/nemoclaw-user-reference/references/architecture.md b/.agents/skills/nemoclaw-user-reference/references/architecture.md index 94958bcc92..d0464cf652 100644 --- a/.agents/skills/nemoclaw-user-reference/references/architecture.md +++ b/.agents/skills/nemoclaw-user-reference/references/architecture.md @@ -2,7 +2,7 @@ # Architecture -NemoClaw has two main components: a TypeScript plugin that integrates with the OpenClaw CLI, and a Python blueprint that orchestrates OpenShell resources. +NemoClaw combines a host CLI, a TypeScript plugin that runs with OpenClaw inside the sandbox, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell. ## System Overview @@ -168,9 +168,9 @@ nemoclaw/ ## NemoClaw Blueprint -The blueprint is a versioned Python artifact with its own release stream. -The plugin resolves, verifies, and executes the blueprint as a subprocess. -The blueprint drives all interactions with the OpenShell CLI. +The blueprint is a versioned YAML package with its own release stream. +The runner resolves, verifies, and applies the blueprint through the OpenShell CLI. +The blueprint defines the sandbox shape, default policies, and inference profiles; the runner performs the OpenShell operations. ```text nemoclaw-blueprint/ diff --git a/.agents/skills/nemoclaw-user-reference/references/commands.md b/.agents/skills/nemoclaw-user-reference/references/commands.md index a8e169a8de..d66eb23209 100644 --- a/.agents/skills/nemoclaw-user-reference/references/commands.md +++ b/.agents/skills/nemoclaw-user-reference/references/commands.md @@ -58,6 +58,11 @@ To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION= $ NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` +When existing sandboxes were created with OpenShell earlier than `0.0.37`, the installer prompts before running the new automatic gateway upgrade path. +For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the installer to back up registered sandbox state, retire the old gateway, install OpenShell `0.0.37`, and restore state during onboarding. +The automatic path is disabled if the existing `nemoclaw` CLI does not advertise `backup-all`; preserve sandbox state manually before retiring the old gateway in that case. +To perform those steps manually, run `nemoclaw backup-all`, retire the old gateway with `openshell gateway destroy -g nemoclaw || openshell gateway destroy`, then rerun the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. + The wizard prompts for a provider first, then collects the provider credential if needed. Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. Credentials are registered with the OpenShell gateway and never persisted to host disk. See Credential Storage (use the `nemoclaw-user-configure-security` skill) for details on inspection, rotation, and migration from earlier releases. @@ -69,8 +74,8 @@ Three tiers are available: | Tier | Description | |------|-------------| | Restricted | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | Full dev tooling and web search. Package installs, model downloads, and inference. No messaging platform access. | -| Open | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | Full dev tooling and web search when the active agent supports web search. Package installs, model downloads, and inference. No messaging platform access. | +| Open | Broad access across third-party services including messaging and productivity. Agent-specific unsupported presets are filtered out. | After selecting a tier, the wizard shows a combined preset and access-mode screen where you can include or exclude individual presets and toggle each between read and read-write access. For details on tiers and the presets each includes, see Network Policies (use the `nemoclaw-user-reference` skill). @@ -87,6 +92,7 @@ Onboarding applies tier defaults and preserves any presets you previously added Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative. Onboarding removes any preset that is not in the list. `skip` leaves the applied set untouched and does not apply tier defaults. +NemoClaw filters tier suggestions and resume selections by active agent support, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. | Value | Behaviour | |-------|-----------| @@ -163,6 +169,10 @@ It verifies that Docker is reachable, warns on untested runtimes such as Podman, The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). If the installed OpenShell version falls outside this range, onboarding exits with an actionable error and a link to compatible releases. +When an existing gateway is detected for reuse, NemoClaw probes the host gateway HTTP endpoint (`http://127.0.0.1:${NEMOCLAW_GATEWAY_PORT}/`) before declaring it reusable, so a gateway whose container is running but whose upstream is still warming up (e.g. immediately after a Docker daemon restart) is rebuilt instead of trusted. +Tune the wait via `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds). +The poll count is clamped to a minimum of `1` so the probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). + #### `--from ` Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. diff --git a/.agents/skills/nemoclaw-user-reference/references/network-policies.md b/.agents/skills/nemoclaw-user-reference/references/network-policies.md index 5fcac9db25..ac18bbbb90 100644 --- a/.agents/skills/nemoclaw-user-reference/references/network-policies.md +++ b/.agents/skills/nemoclaw-user-reference/references/network-policies.md @@ -81,11 +81,13 @@ The baseline policy is always applied regardless of the selected tier. | Tier | Presets included | Description | |------|------------------|-------------| | Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | npm, pypi, huggingface, brew, brave | Full dev tooling and web search. No messaging platform access. | -| Open | npm, pypi, huggingface, brew, brave, slack, discord, telegram, jira, outlook | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | npm, pypi, huggingface, brew, brave when supported | Full dev tooling and web search for agents that support web search. No messaging platform access. | +| Open | npm, pypi, huggingface, brew, brave when supported, slack, discord, telegram, jira, outlook | Broad access across third-party services including messaging and productivity. | After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access. Tier-default presets are pre-selected; additional presets can be added from the full list. +NemoClaw filters tier defaults by the active agent's supported integrations. +For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration. Tier definitions are stored in `nemoclaw-blueprint/policies/tiers.yaml`. diff --git a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md index 3abc3bf7b9..cb56e70c88 100644 --- a/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md +++ b/.agents/skills/nemoclaw-user-reference/references/troubleshooting.md @@ -608,6 +608,19 @@ Changing or exporting it later does not rewrite the baked `openclaw.json` inside If you need a different device-auth setting, rerun onboarding so NemoClaw rebuilds the sandbox image with the desired configuration. For the security trade-offs, refer to Security Best Practices (use the `nemoclaw-user-configure-security` skill). +### `openclaw.json` is empty after changing inference + +Some runtime inference changes can leave `/sandbox/.openclaw/openclaw.json` empty if the write fails partway through. +When that happens, OpenClaw commands may report that the config is empty instead of showing a raw JSON parse error. + +Current NemoClaw sandboxes capture a known-good config baseline after a successful startup. +On the next sandbox startup, NemoClaw restores `openclaw.json` from OpenClaw's last-good copy when available, or from the NemoClaw baseline. +If the sandbox still cannot start or reports that no baseline is available, rebuild it from the host: + +```console +$ nemoclaw rebuild +``` + ### `openclaw channels add` or `remove` is blocked inside the sandbox This is expected. diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 0273ce3ef9..54d1f107a7 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -24,6 +24,20 @@ status: published NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this page to track changes. +## v0.0.40 + +NemoClaw v0.0.40 improves onboarding reliability, local inference setup, and sandbox recovery: + +- `nemoclaw onboard` uses the Docker-driver OpenShell gateway path on macOS with OpenShell 0.0.37, repairs incomplete Docker-driver installs before startup, and installs the platform-specific gateway asset it needs. +- The Docker-driver gateway startup check waits for the gateway port to accept TCP connections before it reports the gateway as healthy, and startup failures now include child process exit details. +- Local Ollama setup requires the authenticated reverse proxy token on every native Ollama API route, including `GET /api/tags`. +- The Linux Ollama install path preflights `zstd` before running the official installer and explains why each sudo-backed setup step needs elevated privileges. +- The onboarding provider menu offers an already-running local vLLM server directly when `localhost:8000` responds, while managed vLLM install and start options remain behind the experimental opt-in. +- Policy tier defaults are filtered by active agent support, so presets such as Brave Search are not reapplied to agents that do not support that integration. +- `nemoclaw connect` checks dashboard forward reachability with a TCP probe before it reports a forward as stale. +- Sandbox startup captures a known-good OpenClaw config baseline and restores it on restart if `/sandbox/.openclaw/openclaw.json` becomes empty. +- The NemoClaw OpenClaw plugin package declares compatibility metadata for OpenClaw package tooling. + ## v0.0.39 NemoClaw v0.0.39 improves several day-two workflows: diff --git a/docs/deployment/sandbox-hardening.md b/docs/deployment/sandbox-hardening.md index 69093a54f2..12e7cf6c73 100644 --- a/docs/deployment/sandbox-hardening.md +++ b/docs/deployment/sandbox-hardening.md @@ -111,8 +111,6 @@ The agent's home directory (`/sandbox`) is writable by default: This writable default is intentional. Seeing the sandbox user create files under `/sandbox` or `/sandbox/.openclaw` in a fresh sandbox does not mean Landlock failed. Landlock still enforces the fixed read-only system paths below. -Use `nemoclaw shields up` from the host to opt into config lockdown for sensitive workloads. -That host-side command layers root ownership, read-only modes, and the immutable flag where available; it does not change the Landlock policy after sandbox creation. System paths remain read-only to prevent agents from: diff --git a/docs/get-started/prerequisites.md b/docs/get-started/prerequisites.md index b6cb75ec36..c6c27cd4dd 100644 --- a/docs/get-started/prerequisites.md +++ b/docs/get-started/prerequisites.md @@ -45,6 +45,8 @@ The sandbox image is approximately 2.4 GB compressed. During image push, the Doc On Linux, the installer can install Docker, start the Docker service, and add your user to the `docker` group. If the group change is not active in the current shell, the installer exits with `newgrp docker` guidance before it starts onboarding. +If you choose the native Linux Ollama install path, the onboard wizard also requires `zstd` for Ollama archive extraction. +On Debian and Ubuntu, NemoClaw installs `zstd` with `apt-get` if it is missing; on other Linux distributions, install `zstd` before onboarding. :::{warning} OpenShell Lifecycle For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md index a40d2757bb..284315dbb0 100644 --- a/docs/get-started/quickstart.md +++ b/docs/get-started/quickstart.md @@ -300,7 +300,7 @@ For example, Slack bot tokens must start with `xoxb-`. ### Choose Network Policy Presets After the sandbox image builds and OpenClaw starts inside the sandbox, NemoClaw asks which network policy tier to apply. -The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search. +The default **Balanced** tier includes common development presets such as npm, PyPI, Hugging Face, Homebrew, and Brave Search when the selected agent supports web search. Use the arrow keys or `j` and `k` to move, Space to select, and Enter to confirm. The preset selector lets you include more destinations, such as GitHub, Jira, Slack, Telegram, or local inference. diff --git a/docs/inference/use-local-inference.md b/docs/inference/use-local-inference.md index 6de9a4c25c..0fdd1c47d1 100644 --- a/docs/inference/use-local-inference.md +++ b/docs/inference/use-local-inference.md @@ -45,6 +45,9 @@ The onboard wizard detects Ollama automatically when it is installed or running If Ollama is installed but not running, NemoClaw starts it for you. On macOS and Linux, the wizard can also offer to install Ollama when it is not present. On WSL, the wizard can use, start, restart, or install Ollama on the Windows host through PowerShell interop. +On Debian and Ubuntu, the native Linux install path checks for `zstd` before it runs the Ollama installer. +If `zstd` is missing, NemoClaw installs it with `apt-get` and explains the sudo prompt before continuing. +On non-apt Linux distributions, install `zstd` first, then rerun onboarding. Run the onboard wizard. diff --git a/docs/project.json b/docs/project.json index 0f18029178..317fa66fdf 100644 --- a/docs/project.json +++ b/docs/project.json @@ -1 +1 @@ -{"name": "nemoclaw", "version": "0.0.39"} +{"name": "nemoclaw", "version": "0.0.40"} diff --git a/docs/reference/commands.md b/docs/reference/commands.md index f14064ee87..57de23f82d 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -96,8 +96,8 @@ Three tiers are available: | Tier | Description | |------|-------------| | Restricted | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | Full dev tooling and web search. Package installs, model downloads, and inference. No messaging platform access. | -| Open | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | Full dev tooling and web search when the active agent supports web search. Package installs, model downloads, and inference. No messaging platform access. | +| Open | Broad access across third-party services including messaging and productivity. Agent-specific unsupported presets are filtered out. | After selecting a tier, the wizard shows a combined preset and access-mode screen where you can include or exclude individual presets and toggle each between read and read-write access. For details on tiers and the presets each includes, see [Network Policies](network-policies.md#policy-tiers). @@ -114,6 +114,7 @@ Onboarding applies tier defaults and preserves any presets you previously added Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative. Onboarding removes any preset that is not in the list. `skip` leaves the applied set untouched and does not apply tier defaults. +NemoClaw filters tier suggestions and resume selections by active agent support, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. | Value | Behaviour | |-------|-----------| diff --git a/docs/reference/network-policies.md b/docs/reference/network-policies.md index 8361a48bb6..b988bbe671 100644 --- a/docs/reference/network-policies.md +++ b/docs/reference/network-policies.md @@ -105,11 +105,13 @@ The baseline policy is always applied regardless of the selected tier. | Tier | Presets included | Description | |------|------------------|-------------| | Restricted | None | Base sandbox only. No third-party network access beyond inference and core agent tooling. | -| Balanced (default) | npm, pypi, huggingface, brew, brave | Full dev tooling and web search. No messaging platform access. | -| Open | npm, pypi, huggingface, brew, brave, slack, discord, telegram, jira, outlook | Broad access across third-party services including messaging and productivity. | +| Balanced (default) | npm, pypi, huggingface, brew, brave when supported | Full dev tooling and web search for agents that support web search. No messaging platform access. | +| Open | npm, pypi, huggingface, brew, brave when supported, slack, discord, telegram, jira, outlook | Broad access across third-party services including messaging and productivity. | After selecting a tier, a combined preset and access-mode screen lets you include or exclude individual presets and toggle each between read (GET only) and read-write (GET + POST/PUT/PATCH) access. Tier-default presets are pre-selected; additional presets can be added from the full list. +NemoClaw filters tier defaults by the active agent's supported integrations. +For example, Hermes onboarding omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration. Tier definitions are stored in `nemoclaw-blueprint/policies/tiers.yaml`. diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index cbf0a9526f..54f3759927 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -638,6 +638,19 @@ Changing or exporting it later does not rewrite the baked `openclaw.json` inside If you need a different device-auth setting, rerun onboarding so NemoClaw rebuilds the sandbox image with the desired configuration. For the security trade-offs, refer to [Security Best Practices](../security/best-practices.md). +### `openclaw.json` is empty after changing inference + +Some runtime inference changes can leave `/sandbox/.openclaw/openclaw.json` empty if the write fails partway through. +When that happens, OpenClaw commands may report that the config is empty instead of showing a raw JSON parse error. + +Current NemoClaw sandboxes capture a known-good config baseline after a successful startup. +On the next sandbox startup, NemoClaw restores `openclaw.json` from OpenClaw's last-good copy when available, or from the NemoClaw baseline. +If the sandbox still cannot start or reports that no baseline is available, rebuild it from the host: + +```console +$ nemoclaw rebuild +``` + ### `openclaw channels add` or `remove` is blocked inside the sandbox This is expected. diff --git a/docs/security/best-practices.md b/docs/security/best-practices.md index bf56c97b6d..5e10c81281 100644 --- a/docs/security/best-practices.md +++ b/docs/security/best-practices.md @@ -250,21 +250,6 @@ For sensitive workloads, use a reviewed host-side immutability workflow after in | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | | Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | -### Locking Config with Shields - -NemoClaw exposes the reviewed host-side immutability workflow through shields commands: - -| Command | Purpose | -|---|---| -| `nemoclaw shields status` | Show whether the sandbox is in default mutable mode, locked mode, or temporarily unlocked mode. | -| `nemoclaw shields up` | Opt into lockdown for sensitive workloads by locking config and state entry points with root ownership, read-only modes, and the immutable flag where available. | -| `nemoclaw shields down --timeout 5m --reason ""` | Temporarily return a previously locked sandbox to the mutable default for maintenance, then auto-restore lockdown. | - -Run shields commands from the host. -They use privileged OpenShell and Kubernetes paths that do not inherit the sandbox process's Landlock context. -Landlock itself stays fixed at sandbox creation; `shields up` does not rewrite the Landlock policy. -Instead, it layers DAC permissions and `chattr +i` over paths that the default Landlock policy intentionally leaves writable. - ### Writable Paths The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`. diff --git a/docs/versions1.json b/docs/versions1.json index 81d18a34f1..9ce07e2010 100644 --- a/docs/versions1.json +++ b/docs/versions1.json @@ -1,6 +1,10 @@ [ { "preferred": true, + "version": "0.0.40", + "url": "https://docs.nvidia.com/nemoclaw/0.0.40/" + }, + { "version": "0.0.39", "url": "https://docs.nvidia.com/nemoclaw/0.0.39/" },