From 456eeb2b0113a2ef844fd9142fe870f189832c33 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 26 Jun 2026 10:56:12 -0700 Subject: [PATCH 1/4] docs: run technical edit pass Signed-off-by: Miyoung Choi --- docs/CONTRIBUTING.md | 3 +- docs/about/ecosystem-hermes.mdx | 20 ++-- docs/about/ecosystem.mdx | 28 +++--- docs/about/how-it-works.mdx | 23 ++--- docs/about/overview.mdx | 46 ++++----- docs/about/release-notes.mdx | 2 +- docs/deployment/brev-web-ui.mdx | 12 +-- docs/deployment/deploy-to-remote-gpu.mdx | 13 +-- docs/deployment/install-openclaw-plugins.mdx | 18 ++-- docs/deployment/sandbox-hardening.mdx | 54 +++++------ docs/get-started/prerequisites.mdx | 14 ++- docs/get-started/quickstart-hermes.mdx | 20 ++-- .../quickstart-langchain-deepagents-code.mdx | 24 ++--- docs/get-started/quickstart.mdx | 39 ++++---- docs/get-started/windows-preparation.mdx | 31 ++++--- .../inference/declarative-agents-manifest.mdx | 25 ++--- docs/inference/inference-options.mdx | 27 +++--- docs/inference/set-up-sub-agent.mdx | 10 +- docs/inference/switch-inference-providers.mdx | 10 +- docs/inference/tool-calling-reliability.mdx | 12 +-- docs/inference/use-local-inference.mdx | 42 ++++----- docs/manage-sandboxes/backup-restore.mdx | 43 +++++---- .../install-plugins-hermes.mdx | 13 +-- docs/manage-sandboxes/lifecycle.mdx | 28 +++--- docs/manage-sandboxes/messaging-channels.mdx | 30 +++--- docs/manage-sandboxes/runtime-controls.mdx | 12 +-- docs/manage-sandboxes/workspace-files.mdx | 28 +++--- docs/monitoring/monitor-sandbox-activity.mdx | 42 ++++----- .../approve-network-requests.mdx | 24 ++--- .../customize-network-policy.mdx | 93 +++++++++++-------- .../integration-policy-examples.mdx | 36 +++---- docs/reference/architecture.mdx | 17 ++-- docs/reference/cli-selection-guide.mdx | 6 +- docs/reference/commands-nemohermes.mdx | 9 +- docs/reference/commands.mdx | 11 ++- docs/reference/enterprise-readiness.mdx | 15 +-- docs/reference/network-policies.mdx | 9 +- docs/reference/platform-support.mdx | 31 ++++--- docs/reference/troubleshooting.mdx | 86 ++++++++--------- docs/resources/agent-skills.mdx | 14 +-- docs/security/best-practices.mdx | 75 +++++++++------ docs/security/credential-storage.mdx | 37 ++++---- docs/security/openclaw-controls.mdx | 58 ++++++------ fern/fern.config.json | 2 +- 44 files changed, 628 insertions(+), 564 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d052a492362..4d230cf5b5c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -172,7 +172,8 @@ Write like you are explaining something to a colleague. Be direct, specific, and ### Things to Avoid -These patterns are common in LLM-generated text and erode trust with technical readers. Remove them during review. +The following patterns are common in LLM-generated text and erode trust with technical readers. +Remove them during review. | Pattern | Problem | Fix | |---|---|---| diff --git a/docs/about/ecosystem-hermes.mdx b/docs/about/ecosystem-hermes.mdx index 659efa38763..1704522323e 100644 --- a/docs/about/ecosystem-hermes.mdx +++ b/docs/about/ecosystem-hermes.mdx @@ -9,14 +9,14 @@ keywords: ["nemoclaw ecosystem", "hermes agent", "nemohermes", "nemoclaw vs open content: type: "concept" --- -NemoClaw provides onboarding, lifecycle management, and Hermes operations within OpenShell containers. +NemoClaw provides onboarding, lifecycle management, and Hermes operations in OpenShell containers. Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected. -This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and how to choose between NemoHermes and OpenShell alone. +This page explains how these projects fit together, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and when to choose NemoHermes or OpenShell directly. ## How the Stack Fits Together -A NemoClaw for Hermes deployment combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw. +A NemoClaw deployment for Hermes combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid @@ -41,9 +41,9 @@ flowchart TB ``` NemoClaw sits above OpenShell in the operator workflow. -It drives OpenShell APIs and CLI to create and configure the sandbox that runs Hermes. +It calls OpenShell APIs and CLI commands to create and configure the sandbox that runs Hermes. Models and endpoints sit behind OpenShell's inference routing. -NemoClaw onboarding wires provider choice into that routing, including the Hermes Provider route when you onboard through `nemohermes`. +NemoClaw onboarding connects your provider choice to that route, including the Hermes Provider route when you onboard through `nemohermes`. The following table shows the scope of each component in the stack. @@ -60,8 +60,8 @@ The difference is who owns the integration work. | Path | What it means | |------|---------------| -| **NemoClaw path** | You adopt the reference stack. NemoClaw's Hermes blueprint encodes a hardened image, default policies, and orchestration so `nemohermes onboard` can create a known-good Hermes-on-OpenShell setup with less custom glue. | -| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | +| **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 tested Hermes-on-OpenShell setup with less custom integration work. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond Custom OpenShell @@ -75,7 +75,7 @@ The following table compares custom OpenShell integration with `nemohermes onboa |---|---|---| | Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. | | Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. | -| Image hardening | Depends on your base image and install steps. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | +| Image hardening | Depends on your base image and install steps. | NemoClaw removes build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | | Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. | | Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates credentials from the host, configures the OpenShell route, and bakes model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. | | Channel messaging | OpenShell delivers channel tokens through its provider system and L7 proxy; you configure Hermes platform adapters manually. | NemoClaw automates supported channel setup during onboarding and bakes Hermes env/config with placeholder tokens that OpenShell resolves at egress. | @@ -85,7 +85,7 @@ The following table compares custom OpenShell integration with `nemohermes onboa ## When to Use Which -Use the following table to decide when to use NemoHermes versus OpenShell alone. +Use this table to choose NemoHermes or OpenShell. | Situation | Prefer | |-----------|--------| @@ -96,7 +96,7 @@ Use the following table to decide when to use NemoHermes versus OpenShell alone. ## Related Topics -- [Overview](overview) describes what NemoClaw is, including capabilities, benefits, and use cases. +- [Overview](overview) defines NemoClaw's 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) installs NemoClaw and launches your first Hermes sandbox. diff --git a/docs/about/ecosystem.mdx b/docs/about/ecosystem.mdx index 44d2b7a8c04..00cb8ac4520 100644 --- a/docs/about/ecosystem.mdx +++ b/docs/about/ecosystem.mdx @@ -9,13 +9,13 @@ keywords: ["nemoclaw ecosystem", "openclaw openshell", "nemoclaw vs openshell", content: type: "concept" --- -NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. +NemoClaw provides onboarding, lifecycle management, and OpenClaw operations in OpenShell containers. -This page describes how these projects form the ecosystem, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and how to choose between NemoClaw and OpenShell. +This page explains how these projects fit together, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and when to choose NemoClaw or OpenShell directly. ## How the Stack Fits Together -A NemoClaw for OpenClaw deployment combines three pieces with distinct scopes: OpenClaw, OpenShell, and NemoClaw. +A NemoClaw deployment for OpenClaw combines three pieces with distinct scopes: OpenClaw, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid @@ -40,9 +40,9 @@ flowchart TB ``` NemoClaw sits above OpenShell in the operator workflow. -It drives OpenShell APIs and CLI to create and configure the sandbox that runs OpenClaw. +It calls OpenShell APIs and CLI commands 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. +NemoClaw onboarding connects your provider choice to that route. The following table shows the scope of each component in the stack. @@ -50,7 +50,7 @@ The following table shows the scope of each component in the stack. |---------|--------| | [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 | The NVIDIA reference stack 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 @@ -59,14 +59,14 @@ The difference is who owns the integration work. | Path | What it means | |------|---------------| -| **NemoClaw path** | You adopt the reference stack. NemoClaw's blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can create a known-good OpenClaw-on-OpenShell setup with less custom glue. | -| **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. | +| **NemoClaw path** | You adopt the reference stack. NemoClaw's blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can create a tested OpenClaw-on-OpenShell setup with less custom integration work. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, OpenClaw install steps, policy YAML, provider setup, and host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond the OpenShell Community Sandbox OpenShell ships a community sandbox for OpenClaw. Running `openshell sandbox create --from openclaw` pulls that package, builds the image, applies the bundled policy, and starts a working sandbox. -This is a valid path, and it produces a running OpenClaw environment with OpenShell isolation. +This path produces a running OpenClaw environment with OpenShell isolation. NemoClaw builds on that foundation with additional security hardening, automation, and lifecycle tooling. The following table compares the two paths. @@ -75,17 +75,17 @@ The following table compares the two paths. |---|---|---| | Sandbox isolation | Yes. OpenShell applies seccomp filters, Landlock filesystem restrictions, privilege dropping, network namespace isolation, and no-new-privileges enforcement. The community sandbox bundles its own policy tailored for OpenClaw. | Yes. NemoClaw applies these through the blueprint and layers a more restrictive policy on top (see rows below). | | 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. | +| Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw removes 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. | | 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. | +| Blueprint versioning | No blueprint. The community sandbox uses the published image version. | 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. | | Process count limits | OpenShell applies seccomp and privilege dropping. You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint to cap the process count and mitigate fork-bomb attacks, on top of OpenShell's seccomp and privilege dropping. | ## When to Use Which -Use the following table to decide when to use NemoClaw versus OpenShell. +Use this table to choose NemoClaw or OpenShell. | Situation | Prefer | |-----------|--------| @@ -96,7 +96,7 @@ Use the following table to decide when to use NemoClaw versus OpenShell. ## Related Topics -- [Overview](overview) describes what NemoClaw is, including capabilities, benefits, and use cases. +- [Overview](overview) defines NemoClaw's 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. - [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven examples, showcases, and integrations that demonstrate complete blueprint patterns. diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index ff5303d9935..2d0b8e143f5 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -14,7 +14,7 @@ import { AgentCli, AgentOnly } from "../_components/AgentGuide"; This page explains how NemoClaw runs supported agents inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. NemoClaw does not replace OpenShell or your chosen agent runtime. -It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, and state helpers. +NemoClaw packages them as a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, and state helpers. OpenClaw sandboxes also load the NemoClaw plugin for managed inference metadata and the `/nemoclaw` slash command. @@ -67,7 +67,7 @@ Reproducible setup ## CLI, Plugin, and Blueprint -NemoClaw is split into integration pieces on the host and in the sandbox image: +NemoClaw separates host orchestration from sandbox image contents. - The _host CLI_ runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations. @@ -85,7 +85,7 @@ NemoClaw is split into integration pieces on the host and in the sandbox image: - The _blueprint_ is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell. -This separation keeps agent-specific sandbox assets focused while allowing host orchestration and blueprint contents to evolve on their own release cadence. +This separation keeps agent-specific sandbox assets focused and lets host orchestration and blueprint contents evolve on separate release cadences. ## Sandbox Creation @@ -104,9 +104,9 @@ Inference requests from the agent never leave the sandbox directly. OpenShell intercepts every inference call and routes it to the configured provider. During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell route, and bakes the matching model reference into the sandbox image. The sandbox then talks to `inference.local`, while the host owns the actual provider credential and upstream endpoint. -If you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. +When you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. -For Hermes, runtime model switches through inference set update `/sandbox/.hermes/config.yaml` without rebuilding the sandbox. +For Hermes, `inference set` updates `/sandbox/.hermes/config.yaml` at runtime without rebuilding the sandbox. ## Protection Layers @@ -120,8 +120,9 @@ The sandbox starts with a default policy that controls network egress, filesyste | Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | -When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. -NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether a failure came from policy denial, DNS, timeout, TLS, or filesystem access. +When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. +Approved endpoints persist for the current session but are not saved to the baseline policy file. +NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether policy denial, DNS, timeout, TLS, or filesystem access caused a failure. ## Next Steps @@ -129,8 +130,8 @@ NemoClaw's runtime context tells supported agents to try allowed network and fil - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths. - Follow [Quickstart with OpenClaw](../get-started/quickstart) to launch your first sandbox. -- Refer to the [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. -- Refer to [Inference Options](../inference/inference-options) for detailed provider configuration. +- Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. +- Read [Inference Options](../inference/inference-options) for detailed provider configuration. - For details on the baseline rules, refer to [Network Policies](../reference/network-policies). - For container-level hardening, refer to [Sandbox Hardening](../manage-sandboxes/sandbox-hardening). @@ -139,8 +140,8 @@ NemoClaw's runtime context tells supported agents to try allowed network and fil - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths. - Follow [Quickstart with Hermes](../get-started/quickstart) to launch your first sandbox. -- Refer to the [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. -- Refer to [Inference Options](../inference/inference-options) for detailed provider configuration. +- Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. +- Read [Inference Options](../inference/inference-options) for detailed provider configuration. - For details on the baseline rules, refer to [Network Policies](../reference/network-policies). diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 178563b22d2..65ce1827acc 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -15,10 +15,11 @@ import { AgentCli, AgentOnly } from "../_components/AgentGuide"; NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside OpenShell containers. NemoClaw provides onboarding, lifecycle management, and agent operations for supported runtimes in OpenShell sandboxes. -It incorporates policy-based privacy and security guardrails, giving you control over your agents' behavior and data handling. -These controls help self-evolving agents run more safely in clouds, on-premises environments, RTX PCs, and DGX Spark. +It adds policy-based privacy and security controls for agent behavior and data handling. +These controls help agents run 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. +NemoClaw pairs hosted inference providers or local model endpoints with a hardened sandbox, routed inference, and declarative egress policy. +This keeps deployments repeatable and easier to constrain. The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). NemoClaw adds the blueprint, CLI, onboarding, and related tooling as the reference way to run supported agents there. @@ -30,13 +31,13 @@ NemoClaw adds the blueprint, CLI, onboarding, and related tooling a ## Key Features -NemoClaw provides the following product capabilities. +NemoClaw provides these product capabilities. | Feature | Description | |---------|-------------| | Guided onboarding | Validates credentials, selects providers, and creates a working sandbox in one command. | | AI-agent docs | Publishes Markdown docs and a small routing skill so AI coding assistants can guide setup, inference configuration, policy management, monitoring, deployment, security review, and troubleshooting. | -| Hardened blueprint | A security-first Dockerfile with capability drops, least-privilege network rules, and declarative policy. | +| Hardened blueprint | A Dockerfile with capability drops, least-privilege network rules, and declarative policy. | | State management | Safe migration of agent state across machines with credential stripping and integrity verification. | | Messaging channels | OpenShell-managed processes connect Telegram, Discord, Slack, and similar platforms to the sandboxed agent. NemoClaw configures channels during onboarding; OpenShell supplies the native constructs, credential flow, and runtime supervision. | | 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. | @@ -44,21 +45,22 @@ NemoClaw provides the following product capabilities. ## Benefits of Using NemoClaw -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. +Autonomous AI agents can make arbitrary network requests, access the host filesystem, and call any inference endpoint. +Without controls, this creates security, cost, and compliance risks that grow as agents run unattended. -NemoClaw provides the following benefits to mitigate these risks. +NemoClaw provides these benefits to mitigate those risks. | Benefit | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------| | Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. The sandbox grants no access by default. | -| Routed inference | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Inference Options](../inference/inference-options). | +| Routed inference | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. See [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 use cases such as the following. +Use NemoClaw for these use cases. | Use Case | Description | |---------------------------|----------------------------------------------------------------------------------------------| @@ -68,25 +70,25 @@ You can use NemoClaw for use cases such as the following. ## Next Steps -Navigate to the following topics to learn more about NemoClaw and how to install and use it. +Use these topics to learn more about NemoClaw and how to install and use it. -- [Architecture Overview](how-it-works) to understand how NemoClaw works. -- [Ecosystem](ecosystem) to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- [Quickstart with OpenClaw](../get-started/quickstart) to install NemoClaw and run your first OpenClaw sandbox. -- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs. -- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations. -- [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. +- Read [Architecture Overview](how-it-works) to understand how NemoClaw works. +- Read [Ecosystem](ecosystem) to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. +- Follow [Quickstart with OpenClaw](../get-started/quickstart) to install NemoClaw and run your first OpenClaw sandbox. +- Read [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs. +- Explore [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) for community-driven blueprint examples, showcases, and integrations. +- Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. -- [Architecture Overview](how-it-works) to understand how NemoClaw works. -- [Ecosystem](ecosystem) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- [Quickstart with Hermes](../get-started/quickstart) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`. -- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs. -- [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations. -- [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. +- Read [Architecture Overview](how-it-works) to understand how NemoClaw works. +- Read [Ecosystem](ecosystem) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. +- Follow [Quickstart with Hermes](../get-started/quickstart) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`. +- Read [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs. +- Explore [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) for community-driven blueprint examples, showcases, and integrations. +- Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index a8d1729e43e..e13a1d582af 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -332,7 +332,7 @@ NemoClaw v0.0.44 improves onboarding reliability, GPU sandbox networking, local - `$$nemoclaw onboard` handles DGX Spark and Jetson hosts more conservatively. Unified-memory GPU detection works for Spark, Jetson defaults to CPU-only sandbox passthrough unless you opt in, and local Ollama validation tolerates slow unified-memory model loads that still fit host memory. - Linux Docker-driver GPU sandboxes preserve `host.openshell.internal` during recreation and inject a reachable DNS resolver when the host uses a systemd-resolved loopback nameserver, which keeps local inference and external DNS working after GPU patching. - Onboarding and sandbox builds fail less often on first run. Preflight can guide missing NVIDIA Container Toolkit setup, Docker builds force BuildKit for Dockerfile bind mounts, npm installs retry transient registry resets, and compatible-endpoint onboarding runs a final inference smoke check before reporting success. -- `$$nemoclaw connect` repairs stale `inference.local` routes before opening the shell, reports local Ollama backend and auth-proxy diagnostics when repair fails, and `--probe-only` keeps dashboard and process recovery from failing just because inference repair needs follow-up. +- `$$nemoclaw connect` repairs stale `inference.local` routes before opening the shell, reports local Ollama backend and auth-proxy diagnostics when repair fails, and `--probe-only` keeps dashboard and process recovery from failing because inference repair needs follow-up. - `$$nemoclaw channels add ` applies the matching built-in network policy preset before rebuild, and rebuilds preserve paused channel state so stopped messaging channels stay disabled after destroy and recreate. - Remote hosts can opt into dashboard forwarding on all interfaces with `NEMOCLAW_DASHBOARD_BIND=0.0.0.0`, and gateway drift checks now stop backup, status, rebuild, recover, and upgrade flows before they trust stale OpenShell state. - Workspace restore uploads backed-up directories file by file, dashboard forwards retry while stopped ports are still releasing, and the in-sandbox OpenClaw gateway respawns after unexpected exits. diff --git a/docs/deployment/brev-web-ui.mdx b/docs/deployment/brev-web-ui.mdx index b38a8a5a2cc..7df1f2af87b 100644 --- a/docs/deployment/brev-web-ui.mdx +++ b/docs/deployment/brev-web-ui.mdx @@ -10,7 +10,7 @@ content: type: "get_started" --- Use the Brev web UI to launch a hosted NemoClaw sandbox from your browser. -This flow provisions a remote VM, configures inference, starts OpenClaw inside an OpenShell sandbox, and opens the OpenClaw dashboard. +Brev provisions a remote VM, configures inference, starts OpenClaw inside an OpenShell sandbox, and opens the OpenClaw dashboard. Use this guide when you want to try NemoClaw without installing the CLI or using a local GPU. @@ -19,7 +19,7 @@ If you want to manage the remote host from a terminal, see [Deploy to a Remote G ## What This Flow Creates -The Brev web flow creates the following resources: +The Brev web flow creates these resources: - A Brev-managed Linux VM. - Docker and the OpenShell runtime on that VM. @@ -41,7 +41,7 @@ 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. -3. Click your profile icon in the top right. +3. Click your profile icon in the upper-right corner. 4. Select **API Keys**. 5. Click **Generate API Key**. 6. Copy the key. It starts with `nvapi-`. @@ -74,10 +74,10 @@ Use the NVIDIA Cloud provider shown on this screen. 3. Click **Create Agent**. -The **Show Other Providers** dropdown appears below the **NVIDIA Cloud** card and can be easy to miss. +The **Show Other Providers** dropdown appears below the **NVIDIA Cloud** card. Click it to expand the provider list. The expanded list includes **OpenAI**, **Anthropic**, and **Google Gemini**. -For these providers, get the API key from the provider's own console before you create the agent. +For these providers, get the API key from the provider console before you create the agent. ### Setup @@ -147,7 +147,7 @@ Brev continues billing while the instance runs. Stop the instance when you finish experimenting. 1. Go back to [brev.nvidia.com](https://brev.nvidia.com). -2. Click **GPUs** in the nav bar. +2. Click **GPUs** in the navigation bar. 3. Find your NemoClaw instance. 4. Click **Stop**. diff --git a/docs/deployment/deploy-to-remote-gpu.mdx b/docs/deployment/deploy-to-remote-gpu.mdx index a0efde2a921..2a408665940 100644 --- a/docs/deployment/deploy-to-remote-gpu.mdx +++ b/docs/deployment/deploy-to-remote-gpu.mdx @@ -12,7 +12,7 @@ skill: priority: 10 --- 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`. +Prefer provisioning the VM first, running the standard NemoClaw installer on that host, and then running `nemoclaw onboard`. ## Prerequisites @@ -45,7 +45,7 @@ When `CHAT_UI_URL` points at one, NemoClaw disables OpenClaw device pairing in t Avoid exposing the dashboard on internet-reachable or shared-network deployments unless you intend that access. -You can list instances from your local machine: +List instances from your local machine: ```bash brev ls --json @@ -70,7 +70,7 @@ Use the origin from the Brev tunnel URL. For example, if the copied URL is `https://example.host/path`, set `CHAT_UI_URL=https://example.host`. If NemoClaw is already installed on the VM, run `nemoclaw onboard` instead of the installer after exporting the variables. -After successful onboarding, you should see output that reports a ready sandbox and the next command to connect: +After successful onboarding, NemoClaw prints output that reports a ready sandbox and the next command to connect: ```text ✓ Sandbox '' is ready @@ -84,7 +84,7 @@ The `nemoclaw deploy` command is deprecated. Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemoclaw onboard` on that host. -Use the legacy compatibility wrapper only when you need the older Brev-specific bootstrap flow: +Use the legacy compatibility wrapper only when you need the older Brev-specific bootstrap flow. ```bash nemoclaw deploy @@ -118,7 +118,7 @@ To reconnect through that legacy flow, run `nemoclaw deploy ` aga ## Monitor the Remote Sandbox -SSH to the instance and run the OpenShell TUI on the remote VM to monitor activity and approve network requests: +Connect to the instance with SSH and run the OpenShell TUI on the remote VM to monitor activity and approve network requests: ```bash ssh 'openshell term' @@ -157,7 +157,8 @@ Any device that can reach the configured dashboard origin can connect without pa ## First-Run Readiness Budget -On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the host builds the sandbox image locally and uploads it into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts. +On a remote GPU host, the first `nemoclaw onboard` usually performs the slowest lifecycle work. +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 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 quantized models (70B+ parameter footprints, NVFP4 weights). diff --git a/docs/deployment/install-openclaw-plugins.mdx b/docs/deployment/install-openclaw-plugins.mdx index f5711b69fb6..fa17a12d5ce 100644 --- a/docs/deployment/install-openclaw-plugins.mdx +++ b/docs/deployment/install-openclaw-plugins.mdx @@ -18,11 +18,11 @@ They are different from NemoClaw-managed agent skills: - **Skills** are `SKILL.md` directories that teach an agent how to perform a task. - **Policy presets** are network-egress rules that control what sandboxed code can reach. -The supported NemoClaw path for OpenClaw plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. +To install supported OpenClaw plugins under NemoClaw, 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. +Place the Dockerfile and everything it needs to `COPY` in one directory. `nemoclaw onboard --from ` uses the Dockerfile's parent directory as the Docker build context. Add a `.dockerignore` next to the Dockerfile to exclude local caches, generated artifacts, model files, or other paths that are not needed by the image build. NemoClaw still applies its own secret-safety exclusions for credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` negates them. @@ -41,7 +41,8 @@ If your plugin does not have a lockfile yet, create one in the plugin project wi ## 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. +Then let OpenClaw refresh its config before NemoClaw starts the sandbox. ```dockerfile ARG SANDBOX_BASE=ghcr.io/nvidia/nemoclaw/sandbox-base:latest @@ -68,7 +69,7 @@ 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. +To run a second sandbox alongside an existing one, use a dedicated build directory and rerun onboarding with the sandbox name and ports you intend to use. ## Build Performance @@ -109,8 +110,8 @@ Order Dockerfile instructions from least-changing to most-changing so warm rebui Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one. -When a build feels slow, set `NEMOCLAW_TRACE=1` before onboarding to capture phase timings that separate context staging, Docker build, image upload, and sandbox readiness. -For the full `--from` build-context rules and trace details, refer to [CLI Commands Reference](../reference/commands). +When a build is slow, set `NEMOCLAW_TRACE=1` before onboarding to capture phase timings that separate context staging, Docker build, image upload, and sandbox readiness. +For the full `--from` build-context rules and trace details, see [CLI Commands Reference](../reference/commands). ## Network Access @@ -122,13 +123,12 @@ For custom preset workflows, refer to [Customize Network Policy](../network-poli ## Common Mistakes -These are the most common places where plugin installation gets mixed up with other NemoClaw extension paths. +The following mistakes commonly mix plugin installation with other NemoClaw extension paths. - Do not use `nemoclaw skill install` for OpenClaw plugins. That command only installs `SKILL.md` agent skills. - Do not put a Dockerfile in a broad directory such as `/tmp` unless you intend to send that whole directory as the Docker build context. - Do not rely on `.dockerignore` to include credential-like paths; NemoClaw excludes those from staged custom build contexts for safety. -- Keep plugin dependencies in the build stage or plugin directory; avoid copying - unrelated host files into the sandbox image. +- Keep plugin dependencies in the build stage or plugin directory, and avoid copying unrelated host files into the sandbox image. ## Next Steps diff --git a/docs/deployment/sandbox-hardening.mdx b/docs/deployment/sandbox-hardening.mdx index f37d84fa8d1..24d16871bac 100644 --- a/docs/deployment/sandbox-hardening.mdx +++ b/docs/deployment/sandbox-hardening.mdx @@ -9,12 +9,12 @@ 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 the attack surface and limit damage from untrusted workloads. ## Removed Unnecessary Tools NemoClaw explicitly purges build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image. -These tools are not needed at runtime and would unnecessarily widen the attack surface. +These tools are not needed at runtime and would widen the attack surface. The runtime image keeps a small set of operational utilities for normal sandbox workflows, including `vi`, `jq`, and `dos2unix`. Use these utilities for lightweight inspection and file cleanup inside the sandbox, but make durable image or policy changes in the NemoClaw source tree and rebuild the sandbox. @@ -33,36 +33,29 @@ Adjust the value with the `--ulimit nproc=512:512` flag if you launch with `dock ## Open File Descriptor Limits -The same ENTRYPOINT also sets `ulimit -n 65536` to cap the number of open file -descriptors a sandbox user can hold. Without this cap the sandbox inherits the -Docker daemon default (`nofile` ~1048576), which can exceed the host runtime -limit and lets a runaway process exhaust file descriptors. The startup script -(`nemoclaw-start.sh`) applies the same limit. +The same ENTRYPOINT also sets `ulimit -n 65536` to cap the number of open file descriptors a sandbox user can hold. +Without this cap, the sandbox inherits the Docker daemon default (`nofile` ~1048576), which can exceed the host runtime limit and let a runaway process exhaust file descriptors. +The startup script (`nemoclaw-start.sh`) applies the same limit. -Adjust the value via the `--ulimit nofile=65536:65536` flag if launching with -`docker run` directly. +Adjust the value with the `--ulimit nofile=65536:65536` flag if you launch with `docker run` directly. -Like the process limit, this is applied to the PID 1 entrypoint process tree -(gateway + agent). `openshell sandbox connect` shells are spawned outside that -tree and still inherit the runtime default (tracked upstream in -NVIDIA/OpenShell#1452), so enforce both limits at the container runtime when -that residual matters to you. +Like the process limit, this limit applies to the PID 1 entrypoint process tree, which includes the gateway and agent. +`openshell sandbox connect` shells spawn outside that tree and still inherit the runtime default (tracked upstream in NVIDIA/OpenShell#1452). +Enforce both limits at the container runtime when that residual risk matters to you. ## Dropping Linux Capabilities 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`. +It removes `CAP_SYS_ADMIN`, `CAP_SYS_PTRACE`, `CAP_NET_RAW`, `CAP_DAC_OVERRIDE`, `CAP_SYS_CHROOT`, `CAP_FSETID`, `CAP_SETFCAP`, `CAP_MKNOD`, `CAP_AUDIT_WRITE`, and `CAP_NET_BIND_SERVICE`. When `setpriv` is available, the entrypoint also removes the remaining privilege-separation capabilities during the switch from root to the `sandbox` and `gateway` users. The bounding-set drop is best effort: if `capsh` or `CAP_SETPCAP` is unavailable the entrypoint logs a warning and continues with the runtime-provided capability set. If `setpriv` is unavailable, the entrypoint falls back to `gosu`. To make the drop fail-closed instead, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment: the agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities. -This is opt-in because hosts that cannot drop capabilities (no `CAP_SETPCAP` — many cloud VMs, Docker Desktop, WSL) are common, and the check covers the agent process tree only. +This is opt-in because many hosts cannot drop capabilities, including cloud VMs, Docker Desktop, and WSL environments without `CAP_SETPCAP`. +The check covers the agent process tree only. -For defense-in-depth, also drop all Linux capabilities at the container runtime -when you launch the image directly: +For defense-in-depth, also drop all Linux capabilities at the container runtime when you launch the image directly: ```bash docker run --rm \ @@ -96,10 +89,11 @@ services: - /tmp:size=64m ``` -> **Note:** The `Dockerfile` itself cannot enforce `--cap-drop`. That is a -> runtime concern controlled by the container orchestrator. Always configure -> capability dropping in your `docker run` flags, Compose file, or Kubernetes -> `securityContext`. + +The `Dockerfile` itself cannot enforce `--cap-drop`. +The container orchestrator controls that runtime setting. +Always configure capability dropping in your `docker run` flags, Compose file, or Kubernetes `securityContext`. + ## Filesystem Layout @@ -121,11 +115,11 @@ 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. -System paths remain read-only to prevent agents from: +System paths remain read-only for these protections: -- Replacing system binaries with trojanized versions -- Modifying DNS resolution or TLS trust stores -- Tampering with libraries or shell configuration outside `/sandbox` +- Agents cannot replace system binaries with trojanized versions. +- Agents cannot modify DNS resolution or TLS trust stores. +- Agents cannot tamper with libraries or shell configuration outside `/sandbox`. The image build pre-creates locked shell init files `.bashrc` and `.profile` without proxy entries. System-wide shell hooks that read `/tmp/nemoclaw-proxy-env.sh` source the runtime proxy configuration. @@ -138,13 +132,13 @@ The NemoClaw sandbox policy uses `compatibility: best_effort`, which means Landl On such kernels, protection falls back to DAC (file ownership and permissions) only. Files outside the writable paths would be inaccessible to the agent regardless of DAC permissions. -Operators should verify Landlock availability: +Verify Landlock availability: ```bash ls /sys/kernel/security/landlock ``` -For production deployments, kernel 5.13+ with Landlock enabled is strongly recommended. +For production deployments, use kernel 5.13+ with Landlock enabled. The `test/e2e/e2e-cloud-experimental/checks/04-landlock-readonly.sh` script validates enforcement at runtime. ## References diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index f26536ecb12..19c697efcd2 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -42,7 +42,9 @@ The installer also requires `strings` from `binutils` to verify the OpenShell bi 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. +Members of the `docker` group can control the daemon with root-level impact. +Grant this access only to trusted local accounts. +On shared or managed systems, use your organization's approved Docker access path. For background, review Docker's [daemon attack surface guidance](https://docs.docker.com/engine/security/#docker-daemon-attack-surface). @@ -62,7 +64,9 @@ Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway sta -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. +On Linux hosts running Docker 26 or later with the [containerd image store](https://docs.docker.com/engine/storage/containerd/) enabled, `$$nemoclaw onboard` transparently builds a `fuse-overlayfs`-enabled cluster image. +The containerd image store is the install-time default for fresh `docker-ce` installations on Ubuntu 24.04 and similar distros. +The `fuse-overlayfs`-enabled image bypasses a kernel-level nested-overlay limitation in k3s. You do not need manual setup. Refer to the [troubleshooting guide](../reference/troubleshooting) for the override knobs and a manual `daemon.json` alternative. @@ -84,6 +88,6 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC ## Next Steps -- [Prepare Windows for NemoClaw](prerequisites/windows-preparation) if you are using Windows. -- [Quickstart](quickstart) to install NemoClaw and launch your first sandboxed agent. -- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs before setup. +- Use [Prepare Windows for NemoClaw](prerequisites/windows-preparation) if you are using Windows. +- [Quickstart](quickstart) installs NemoClaw and launches your first sandboxed agent. +- [AI Agent Docs](../resources/agent-skills) lets your AI coding assistant fetch NemoClaw Markdown docs before setup. diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index a88c58af6d2..9666d30962f 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -11,7 +11,7 @@ content: skill: priority: 20 --- -Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent. +Use NemoHermes 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. Review the [Prerequisites](prerequisites) before starting. @@ -31,7 +31,7 @@ export NEMOCLAW_AGENT=hermes curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -If a headless host needs to expose the Hermes dashboard through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. +To expose the Hermes dashboard from a headless host through a remote URL or tunnel, set `CHAT_UI_URL` before onboarding. Use the externally reachable origin for the dashboard port `18789`. NemoClaw derives the forwarded dashboard port from this value, binds the forward for remote access when the origin is non-loopback, and prints the final dashboard URL in the ready summary. The OpenAI-compatible API remains available separately on port `8642`. @@ -86,7 +86,7 @@ Hermes uses an agent-specific baseline policy that allows the Hermes binary and ## Use Non-Interactive Setup For CI or scripted installs, set the required environment variables before running the installer. -The example below uses NVIDIA Endpoints and creates a sandbox named `my-hermes`. +This example uses NVIDIA Endpoints and creates a sandbox named `my-hermes`. ```bash export NEMOCLAW_AGENT=hermes @@ -105,7 +105,7 @@ For the recovery commands, refer to [Previous onboarding session failed](../refe When onboarding completes, NemoClaw prints the sandbox name, model, lifecycle commands, the Hermes dashboard URL, and the OpenAI-compatible API URL. Hermes exposes its built-in browser dashboard on port `18789`. -NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients, and the summary now announces both URLs. +NemoClaw also forwards the OpenAI-compatible API on port `8642` for local clients, and the summary announces both URLs. NemoClaw builds the Hermes dashboard assets into the sandbox image, so the dashboard starts without running `npm` as the sandbox user under `/opt/hermes`. Dashboard chat uses the prebuilt `/opt/hermes/ui-tui` bundle. If you need to recover the Hermes dashboard manually, use `hermes dashboard --tui --skip-build` so recovery does not try to rebuild assets under root-owned install paths. @@ -141,7 +141,7 @@ Manage later ────────────────────────────────────────────────── ``` -To chat with the agent from a terminal, follow these steps: +To chat with the agent from a terminal, follow these steps. 1. Connect to the sandbox and start the Hermes CLI. @@ -158,7 +158,7 @@ To chat with the agent from a terminal, follow these steps: ## Open the Dashboard The onboard flow starts the dashboard port forward automatically. -Open the dashboard from the host: +Open the dashboard from the host. ```bash nemohermes my-hermes dashboard-url --quiet @@ -222,7 +222,7 @@ nemohermes my-hermes destroy ## Next Steps -- [Inference Options](../inference/inference-options) to choose a provider and model. -- [Commands](../reference/commands) to see the full `nemohermes` alias behavior. -- [Backup and Restore](../manage-sandboxes/backup-restore) to preserve sandbox state before destructive operations. -- [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) to inspect OpenShell events and sandbox logs. +- [Inference Options](../inference/inference-options) explains how to choose a provider and model. +- The [Commands](../reference/commands) page explains the full `nemohermes` alias behavior. +- [Backup and Restore](../manage-sandboxes/backup-restore) explains how to preserve sandbox state before destructive operations. +- [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) explains how to inspect OpenShell events and sandbox logs. diff --git a/docs/get-started/quickstart-langchain-deepagents-code.mdx b/docs/get-started/quickstart-langchain-deepagents-code.mdx index c9191668dff..bdee23e48b8 100644 --- a/docs/get-started/quickstart-langchain-deepagents-code.mdx +++ b/docs/get-started/quickstart-langchain-deepagents-code.mdx @@ -15,7 +15,7 @@ content: type: "get_started" --- -Use this guide when you want NemoClaw to build an OpenShell sandbox with the `dcode` terminal coding agent installed and configured for NemoClaw-managed inference. +Use this guide to build an OpenShell sandbox with the `dcode` terminal coding agent installed and configured for NemoClaw-managed inference. ## Onboard @@ -58,13 +58,14 @@ For project-specific Python dependencies, create a separate virtual environment Deep Agents Code state lives under `/sandbox/.deepagents`. NemoClaw snapshot and rebuild flows preserve the app state directory, skills, generated config, and hooks config when those files exist. Run `nemoclaw snapshot create` after active `dcode` tasks finish. -For `langchain-deepagents-code` sandboxes, NemoClaw refuses before backup when it detects an active `dcode` task or cannot verify that the state tree is idle. +For `langchain-deepagents-code` sandboxes, NemoClaw refuses backup when it detects an active `dcode` task or cannot verify that the state tree is idle. NemoClaw intentionally does not preserve `.env` or `.mcp.json` because users may put Tavily, LangSmith, MCP service, or provider credentials there, and this managed harness disables MCP at runtime. ## Optional Web Search -Deep Agents Code can use Tavily web search when you provide a Tavily credential in the runtime environment. -NemoClaw does not enable Tavily or LangSmith by default for this harness. The sandbox policy denies `api.tavily.com` and `api.smith.langchain.com` until you opt in. +Deep Agents Code uses Tavily web search when you provide a Tavily credential in the runtime environment. +NemoClaw does not enable Tavily or LangSmith by default for this harness. +The sandbox policy denies `api.tavily.com` and `api.smith.langchain.com` until you opt in. To enable Tavily, apply the maintained `tavily` policy preset so the sandbox may reach the Tavily API, then supply the credential. @@ -87,13 +88,14 @@ nemoclaw policy-remove tavily --yes ### Optional Tracing (LangSmith) -LangSmith tracing is **not a supported integration** for this managed harness yet. +NemoClaw does not support LangSmith tracing for this managed harness yet. `start.sh` forwards the non-secret `LANGSMITH_TRACING`/`LANGSMITH_PROJECT` toggles if set, but no policy preset opens `api.smith.langchain.com` and no supported mechanism injects `LANGSMITH_API_KEY`. -If you need tracing, [add the egress endpoints manually](../network-policy/customize-network-policy); treat it as unsupported until NemoClaw ships a maintained `langsmith` preset. +If you need tracing, [add the egress endpoints manually](../network-policy/customize-network-policy). +Treat it as unsupported until NemoClaw ships a maintained `langsmith` preset. ## Troubleshooting -Use normal sandbox lifecycle commands: +Use normal sandbox lifecycle commands. ```bash nemoclaw status @@ -108,7 +110,7 @@ There is no dashboard port or long-running gateway process for this harness. ## Next Steps -- [Inference Options](../inference/inference-options) to choose a provider and model. -- [Backup and Restore](../manage-sandboxes/backup-restore) for snapshot and rebuild preservation details. -- [Runtime Controls](../manage-sandboxes/runtime-controls) for sandbox mutability and host-side control boundaries. -- [Troubleshooting](../reference/troubleshooting) for common setup and runtime issues. +- [Inference Options](../inference/inference-options) explains how to choose a provider and model. +- [Backup and Restore](../manage-sandboxes/backup-restore) explains snapshot and rebuild preservation. +- [Runtime Controls](../manage-sandboxes/runtime-controls) explains sandbox mutability and host-side control boundaries. +- [Troubleshooting](../reference/troubleshooting) covers common setup and runtime issues. diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 67a38b5f63d..860bcc894a8 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -25,7 +25,7 @@ Refer to [AI Agent Docs](../resources/agent-skills). ## Install NemoClaw and Onboard an OpenClaw Agent -Download and run the installer script. +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. @@ -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`: +You can also pass the installer flag through `bash -s`. ```bash curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -s -- --yes-i-accept-third-party-software @@ -79,7 +79,8 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash On DGX Spark, DGX Station, and Windows WSL, an interactive installer offers express install after you accept the third-party software notice. Express install switches onboarding to non-interactive mode, allows `sudo` password prompts for required host changes, and selects the managed local inference path for that platform. On DGX Spark and DGX Station, express install selects managed vLLM; DGX Spark uses `qwen3.6-35b-a3b-nvfp4` by default. -Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default, using the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. +Unless `NEMOCLAW_POLICY_TIER` is set, it applies sandbox policy in `suggested` mode with the `balanced` tier by default. +That tier uses the base sandbox policy plus supported package, model, web-search, local-inference, and read-only weather presets. On DGX Spark, express install uses `my-spark-assistant` as the sandbox name unless `NEMOCLAW_SANDBOX_NAME` is already set. On WSL, express install selects the Windows-host Ollama setup path. Set `NEMOCLAW_NO_EXPRESS=1` to skip the express prompt, or set `NEMOCLAW_PROVIDER` before launching the installer when you want to choose a provider yourself. @@ -116,7 +117,8 @@ The inference provider prompt presents a numbered list. Choose [1]: ``` -Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. +Pick the option that matches where you want inference traffic to go. +The provider you choose determines 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. A configured blueprint router profile makes the Model Router option appear. @@ -169,7 +171,9 @@ For example, if you picked an OpenAI-compatible endpoint, the summary looks like Apply this configuration? [Y/n]: ``` -The default is `Y`, so you can press Enter one time to continue. Answer `n` to abort cleanly, fix the entries, and re-run `nemoclaw onboard`. +The default is `Y`. +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. @@ -234,11 +238,12 @@ Manage later [INFO] === Installation complete === ``` -If you picked a different option, the `Model` line shows that provider's model and label instead. For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, `nvidia-routed (Model Router)`, or ` (Other OpenAI-compatible endpoint)`. +If you picked a different option, the `Model` line shows that provider's model and label instead. +For example, you might see `gpt-5.4 (OpenAI)`, `claude-sonnet-4-6 (Anthropic)`, `gemini-2.5-flash (Google Gemini)`, `llama3.1:8b (Local Ollama)`, `nvidia-routed (Model Router)`, or ` (Other OpenAI-compatible endpoint)`. ## Run Your First Agent Prompt -You can chat with the agent from the terminal or the browser. +Chat with the agent from the terminal or the browser. ### Open the OpenClaw UI in a Browser to Chat with the Agent @@ -269,16 +274,16 @@ openclaw tui ## Next Steps -Navigate to the following topics to learn more about NemoClaw. +Use these topics to learn more about NemoClaw. -- [NemoClaw Overview](../about/overview) to learn what NemoClaw is and its capabilities. -- [Architecture Overview](../about/how-it-works) to understand how NemoClaw works. -- [Ecosystem](../about/ecosystem) to understand how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs. +- [NemoClaw Overview](../about/overview) explains what NemoClaw is and what it supports. +- [Architecture Overview](../about/how-it-works) explains how NemoClaw works. +- [Ecosystem](../about/ecosystem) explains how OpenClaw, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. +- [AI Agent Docs](../resources/agent-skills) lets your AI coding assistant fetch NemoClaw Markdown docs. -Use the following topics to learn how to use NemoClaw. +Use these topics to work with NemoClaw. -- [Manage NemoClaw sandboxes](../manage-sandboxes/lifecycle) for port forwards, rebuilds, upgrades, and uninstall. -- [Inference Options](../inference/inference-options) to use a different model or endpoint. -- [Network Policies](../network-policy/approve-network-requests) to manage egress approvals. -- [Troubleshooting](../reference/troubleshooting) for common error messages and resolution steps. +- [Manage NemoClaw sandboxes](../manage-sandboxes/lifecycle) covers port forwards, rebuilds, upgrades, and uninstall. +- [Inference Options](../inference/inference-options) explains how to use a different model or endpoint. +- [Network Policies](../network-policy/approve-network-requests) explains how to manage egress approvals. +- [Troubleshooting](../reference/troubleshooting) covers common error messages and resolution steps. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 58642d7b1ea..f288109334d 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -11,7 +11,7 @@ content: --- import { AgentOnly } from "../_components/AgentGuide"; -You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. +Run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. Complete these steps before following the [Quickstart](../quickstart). @@ -40,7 +40,7 @@ Verify the following before you begin: -## Option: Use the Bootstrap Script +## Use the Bootstrap Script Open Windows PowerShell on the Windows host and run the bootstrap script: @@ -70,9 +70,13 @@ When Windows preparation is complete, it opens Ubuntu and prints the standard in curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -If the bootstrap script reports that Ubuntu cannot reach Docker, open Docker Desktop Settings and confirm that Docker Desktop enables WSL integration for Ubuntu (**Settings** > **Resources** > **WSL integration**), make sure Docker Desktop is running, then rerun the script. +If the bootstrap script reports that 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/). +If the bootstrap script reports that `winget.exe` is not available, install **App Installer** from the Microsoft Store. +This is common on Windows Server or stripped Windows installs. +**App Installer** provides `winget`. +You can also download and install Docker Desktop manually from [docker.com](https://www.docker.com/products/docker-desktop/). After you install Docker Desktop, rerun the bootstrap script. The script skips the install step after it detects Docker Desktop. @@ -80,7 +84,7 @@ The manual steps below describe the same Windows preparation pieces and are usef ## Enable WSL 2 -Open an elevated PowerShell (Run as Administrator): +Open an elevated PowerShell as Administrator. ```powershell wsl --install --no-distribution @@ -92,13 +96,14 @@ Reboot if prompted. ## Install and Register Ubuntu -After reboot, open an elevated PowerShell again: +After reboot, open an elevated PowerShell again. ```powershell wsl --install -d Ubuntu-24.04 ``` -Let the distribution launch and complete first-run setup (pick a Unix username and password), then type `exit` to return to PowerShell. +Let the distribution launch and complete first-run setup. +Pick a Unix username and password, then type `exit` to return to PowerShell. Do not use the `--no-launch` flag. @@ -143,7 +148,7 @@ If you see "Cannot connect to the Docker daemon", confirm that Docker Desktop is ## Set Up Local Inference with Ollama (Optional) If you plan to select Ollama as your inference provider during onboarding, use one Ollama instance that WSL can reach. -You can install Ollama inside WSL yourself: +Run this command to install Ollama inside WSL. ```bash curl -fsSL https://ollama.com/install.sh | sh @@ -164,14 +169,18 @@ Use one instance, or move one of them to a different port before running `$$nemo Your Windows environment is ready. If you used the bootstrap script, follow the installer command it printed inside Ubuntu. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](../quickstart) to install NemoClaw and launch your first sandbox. +If you prepared Windows manually, open a WSL terminal. +Type `wsl` in PowerShell, or open Ubuntu from Windows Terminal. +Then continue with the [Quickstart](../quickstart) to install NemoClaw and launch your first sandbox. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with [Quickstart with Hermes](../quickstart) to install NemoClaw and launch your first Hermes sandbox. +If you prepared Windows manually, open a WSL terminal. +Type `wsl` in PowerShell, or open Ubuntu from Windows Terminal. +Then continue with [Quickstart with Hermes](../quickstart) to install NemoClaw and launch your first Hermes sandbox. All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide. +For Windows-specific troubleshooting, see the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide. diff --git a/docs/inference/declarative-agents-manifest.mdx b/docs/inference/declarative-agents-manifest.mdx index 1c97b7681a9..c970f683c1a 100644 --- a/docs/inference/declarative-agents-manifest.mdx +++ b/docs/inference/declarative-agents-manifest.mdx @@ -26,17 +26,17 @@ status: published NemoClaw can bake a multi-agent OpenClaw layout into a sandbox image from a single checked-in manifest. Supply the manifest at onboard time with `--agents ` and NemoClaw embeds the resulting `agents.list` entries, per-agent overrides, and `agents.defaults.subagents` block into `openclaw.json` during the image build. -The schema mirrors OpenClaw's own `agents.list[]` field names, so the same keys you read in [OpenClaw's sub-agents reference](https://docs.openclaw.ai/tools/subagents) appear verbatim in the manifest. +The schema mirrors OpenClaw's own `agents.list[]` field names, so the same keys from [OpenClaw's sub-agents reference](https://docs.openclaw.ai/tools/subagents) appear verbatim in the manifest. -## When To Use This +## When to Use This Use `--agents` when: -- You want a repeatable, GitOps-friendly multi-agent sandbox (manager + workers, or a research / writing split). +- You want a repeatable, GitOps-friendly multi-agent sandbox, such as a manager-worker layout or a research and writing split. - A secondary agent needs its own model (different size, different capability profile). - You want OpenClaw's `sessions_spawn` validator to enforce a fixed spawn allowlist, not the broad default. -For a single primary agent on the configured inference route, no manifest is required — the canonical `main` agent is always baked in as the default. +For a single primary agent on the configured inference route, no manifest is required because the canonical `main` agent is always baked in as the default. ## Invocation @@ -97,7 +97,7 @@ Operators cannot set `default: true` on a secondary agent and cannot rename the | `id` | yes | Lowercase alphanumeric + `_`/`-`, 1-32 chars, must start with a letter. Cannot be `main`. | | `workspace` | auto-filled | Defaults to `/sandbox/.openclaw/workspace-`. Must match the canonical sandbox layout if supplied. | | `agentDir` | auto-filled | Defaults to `/sandbox/.openclaw/agents/`. Must match the canonical sandbox layout if supplied. | -| `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]` — secondary agents inherit no tools by default. | +| `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]`; secondary agents inherit no tools by default. | | `description` | no | Human-readable. Baked verbatim. | | `model` | no | `provider/model` reference. The provider must match the onboard provider; cross-provider manifests are not supported. | | `subagents` | no | OpenClaw-native sub-agent delegation policy. See below. | @@ -114,13 +114,15 @@ Both `main.subagents` and `agents[].subagents` use the same shape, which mirrors | `thinking` | string | Default thinking level for spawned sub-agents. | | `requireAgentId` | boolean | Force the model to pass `agentId` explicitly to `sessions_spawn` rather than defaulting to self. | -`maxSpawnDepth` is **not accepted per-agent** — OpenClaw only honours it on `agents.defaults.subagents`, so the manifest exposes it only under the top-level `defaults` block. +OpenClaw only honors `maxSpawnDepth` on `agents.defaults.subagents`, so the manifest exposes it only under the top-level `defaults` block. +Do not set `maxSpawnDepth` per agent. ### Multi-Model Sandboxes When a secondary agent declares its own `model` (or `subagents.model`), NemoClaw widens the baked `models.providers[].models[]` array with one entry per unique `provider/model` reference. The base `contextWindow`, `maxTokens`, `reasoning`, and `input` settings from the onboard route apply to each appended entry. -Per-model overrides beyond these defaults are out of scope for v1 — edit the generated `openclaw.json` in-place if you need finer control. +Per-model overrides beyond these defaults are out of scope for v1. +Edit the generated `openclaw.json` in place if you need finer control. ## Manager-Worker Example @@ -158,7 +160,7 @@ Workspaces under `/sandbox/.openclaw/workspace-` are preserved across rebuil For ad-hoc per-agent edits inside an existing sandbox (no rebuild), use the in-sandbox CLI: `nemoclaw agents add|delete|list`. The manifest path is for fixed, checked-in layouts; the CLI passthrough is for interactive work. -## Apply To An Existing Sandbox +## Apply to an Existing Sandbox `nemoclaw agents apply -f ` reconciles the live sandbox roster against the manifest **without a rebuild**. The verb lists current agents via `openclaw agents list --json`, diffs them against the manifest, and drives `openclaw agents add|delete` per item. @@ -168,13 +170,14 @@ Per-agent `model`, `subagents.*`, top-level `defaults`, and `main` overrides req nemoclaw my-assistant agents apply -f ./agents.yaml --yes ``` -The flag pair `--yes / --non-interactive` is required for scripted use: `--yes` confirms the printed roster diff, and `--non-interactive` makes the verb fail fast when `--yes` is absent rather than waiting for an interactive prompt that scripted callers cannot deliver. +The `--yes` and `--non-interactive` flags are required for scripted use. +`--yes` confirms the printed roster diff, and `--non-interactive` makes the verb fail fast when `--yes` is absent rather than waiting for an interactive prompt that scripted callers cannot deliver. ## Next Steps -Use the following resources for more information: +Continue with these resources: - Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for the runtime semantics of `sessions_spawn`, `subagents.allowAgents`, and nesting depth. - Refer to [Set Up Task-Specific Sub-Agents](set-up-sub-agent) for the in-sandbox path that edits `agents.list` directly without a rebuild. -- Refer to [Switch Inference Providers](switch-inference-providers) before swapping the primary onboard provider — per-agent `model` refs must share that provider. +- Refer to [Switch Inference Providers](switch-inference-providers) before swapping the primary onboard provider because per-agent `model` refs must share that provider. - Refer to [Workspace Files](../manage-sandboxes/workspace-files) to understand how per-agent `workspace-` directories are provisioned and persisted across rebuilds. diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 9554f798305..fe69399297d 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -12,7 +12,7 @@ content: 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. +During onboarding, the wizard presents a numbered list of providers to choose from. Your selection determines where NemoClaw routes the agent's inference traffic. @@ -150,7 +150,7 @@ NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare - `ensurepip`, `pyexpat`, `ssl`, and `venv` all import without error. If no candidate qualifies, onboarding aborts and prints the real failure for each candidate. -This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails to dlopen against the older system `libexpat` on macOS. +This surfaces issues like Homebrew `python@3.14`, whose `pyexpat` extension fails to load against the older system `libexpat` on macOS. To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `$$nemoclaw onboard`: @@ -159,10 +159,11 @@ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 $$nemoclaw onboard ``` The pin is strict. -NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`. +NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different interpreter on `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. +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 interpreter. ## Caveated Local Options @@ -175,7 +176,7 @@ An already-running vLLM server appears directly in the onboarding selection list | 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 when vLLM is already running. Can install or start a managed vLLM container by default on DGX Spark/Station and after opt-in on generic Linux NVIDIA GPU hosts. | -For setup instructions, refer to [Use a Local Inference Server](use-local-inference). +For setup instructions, see [Use a Local Inference Server](use-local-inference). ## Validation @@ -255,8 +256,7 @@ NEMOCLAW_PROVIDER=custom \ ### Selecting the API Path For the compatible-endpoint provider, `/v1/chat/completions` is the default. -NemoClaw tests streaming events during onboarding and uses chat completions -without probing the Responses API. +NemoClaw tests streaming events during onboarding and uses chat completions without probing the Responses API. To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: @@ -264,18 +264,15 @@ To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboar NEMOCLAW_PREFERRED_API=openai-responses $$nemoclaw onboard ``` -The wizard then probes `/v1/responses` and only selects it when streaming -support is complete. -If the probe fails, the wizard falls back to `/v1/chat/completions` -automatically. +The wizard then probes `/v1/responses` and only selects it when streaming support is complete. +If the probe fails, the wizard falls back to `/v1/chat/completions` automatically. You can use this variable in both interactive and non-interactive mode. | Variable | Values | Default | |---|---|---| | `NEMOCLAW_PREFERRED_API` | `openai-completions`, `openai-responses` | `openai-completions` for compatible endpoints | -If you already onboarded and the sandbox is failing at runtime, re-run `$$nemoclaw onboard` to re-probe the endpoint and bake the correct API path -into the image. +If you already onboarded and the sandbox is failing at runtime, re-run `$$nemoclaw onboard` to re-probe the endpoint and bake the correct API path into the image. Refer to [Switch Inference Models](switch-inference-providers) for more information. ## Anthropic-Compatible Server @@ -311,7 +308,7 @@ In interactive runs, the managed vLLM path lists the supported registry models f Press **Enter** to use the default model, or choose a numbered entry to serve another validated model with its matching `vllm serve` flags. NemoClaw pulls the vLLM image, downloads model weights into `~/.cache/huggingface`, starts the `nemoclaw-vllm` container on `localhost:8000`, streams Hugging Face download progress, and polls `/v1/models` until the model is ready. Managed DGX Spark and DGX Station profiles use the stable NGC `nvcr.io/nvidia/vllm:26.05.post1-py3` container image. -If Docker pull output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. +If `docker pull` output stops making progress, a watchdog stops the stalled pull instead of failing slow but active downloads on a fixed wall-clock timeout. If vLLM never becomes ready, NemoClaw prints a short tail of the vLLM container logs before exiting. The first run can take 10 to 30 minutes. Later runs reuse the cached image and model weights. @@ -378,7 +375,7 @@ NEMOCLAW_PROVIDER=install-vllm \ ``` NemoClaw accepts `HUGGING_FACE_HUB_TOKEN` as an alternative. -The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401. +The token check runs on the host before any `docker pull`, so a missing or empty token aborts onboarding before bandwidth is spent on a 401. ### Add Managed-vLLM Serve Arguments diff --git a/docs/inference/set-up-sub-agent.mdx b/docs/inference/set-up-sub-agent.mdx index 2bfdfc2ba8c..83c6b2ae3c1 100644 --- a/docs/inference/set-up-sub-agent.mdx +++ b/docs/inference/set-up-sub-agent.mdx @@ -14,7 +14,7 @@ skill: OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents). Use that page as the source of truth for how OpenClaw sub-agents work. -This NemoClaw page covers the sandbox-specific pieces: where the OpenClaw config lives, where to put per-agent credentials, which writable workspace path agents should use, and how the Omni VLM demo maps onto those paths. +This page covers the sandbox-specific pieces: where the OpenClaw config lives, where to put per-agent credentials, which writable workspace path agents should use, and how the Omni VLM demo maps onto those paths. ## NemoClaw Sandbox Paths @@ -57,7 +57,7 @@ These commands run on the host that owns the sandbox containers and discover the If you have not created a sandbox yet, onboard one first, such as `my-assistant`. -Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it back. +Fetch the current OpenClaw config from the sandbox, patch it with your auxiliary provider and `agents.list` changes, then upload it. On Docker-driver sandboxes, run these commands from the host that owns the sandbox containers. The container name includes a runtime suffix, so discover it from the OpenShell sandbox label: @@ -158,7 +158,7 @@ Check the following: 1. `OPENCLAW_GATEWAY_URL` in the gateway process environment targets the sandbox interface address, not `127.0.0.1`. 2. The active policy allows that address and port. Custom `NEMOCLAW_DASHBOARD_PORT` or proxy subnet values need a matching `openshell policy update`. -3. Do not point the dial-back at `127.0.0.1` — the proxy denies loopback regardless of policy. +3. Do not point the dial-back at `127.0.0.1`; the proxy denies loopback regardless of policy. ## Add Delegation Instructions @@ -174,7 +174,7 @@ Adapt that file for other task-specific models. ## Demo Assets -Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) repository for runnable Omni example assets: +Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-demo) repository for runnable Omni assets: - `vlm-subagent-guide.md` for a command-by-command walkthrough. - `vlm-subagent/openclaw-patch.py` for patching `openclaw.json`. @@ -183,7 +183,7 @@ Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-dem ## Next Steps -Use the following resources for more information: +Continue with these resources: - Refer to [OpenClaw Sub-Agents](https://docs.openclaw.ai/tools/subagents) for `sessions_spawn`, `agents.list`, nesting, tool policy, and auth behavior. - Refer to [Switch Inference Providers](switch-inference-providers) to change the primary orchestration model instead of adding a sub-agent model. diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index b2970dca225..1c1545386bd 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -19,7 +19,7 @@ You do not need to restart the sandbox. ## Prerequisites - A running NemoClaw sandbox. -- The OpenShell CLI on your `PATH`, which NemoClaw uses under the hood. +- The OpenShell CLI on your `PATH`, which NemoClaw uses internally. ## Switch to a Different Model @@ -32,8 +32,7 @@ For OpenClaw, it updates `agents.defaults.model.primary` and the matching provid Use `$$nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, `model.provider: custom`, API-family mode when needed, and the OpenShell proxy API-key placeholder) without rebuilding or restarting Hermes. -Pass `--sandbox ` when you do not want to use the default registered sandbox. -Under `$$nemoclaw`, pass `--sandbox ` when you have registered more than one Hermes sandbox. +Pass `--sandbox ` when you do not want to use the default registered sandbox or when you have registered more than one Hermes sandbox. @@ -120,8 +119,7 @@ NEMOCLAW_PREFERRED_API=openai-responses $$nemoclaw 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 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. +A fresh `$$nemoclaw onboard` is the reliable fix because it updates both the session and the baked image. ## Cross-Provider Switching @@ -275,7 +273,7 @@ The status output includes the active provider, model, and endpoint with the res - The host keeps provider credentials. - The sandbox continues to use `inference.local`. -- `$$nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash. +- `$$nemoclaw inference set` patches the selected running OpenClaw sandbox config and recomputes its config hash. - Use `$$nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. - Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. diff --git a/docs/inference/tool-calling-reliability.mdx b/docs/inference/tool-calling-reliability.mdx index 9a5a4c2a5ab..5cfcffb4507 100644 --- a/docs/inference/tool-calling-reliability.mdx +++ b/docs/inference/tool-calling-reliability.mdx @@ -9,8 +9,8 @@ keywords: ["nemoclaw tool calling", "ollama tool calls", "vllm tool-call-parser" 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 supports privacy, cost control, and offline development, but tool-calling agents place stricter demands on the model server than chat-only use. +The model server must return structured `tool_calls`, not a JSON-shaped string inside normal assistant text. Use this page when the TUI shows raw JSON such as: @@ -67,7 +67,7 @@ vllm serve /models/Hermes-3-Llama-3.1-8B \ --port 8000 ``` -For a Docker Compose setup: +For a Docker Compose setup, use: ```yaml services: @@ -114,8 +114,7 @@ If the endpoint does not require authentication, set `COMPATIBLE_API_KEY` to any 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: +If you are intentionally testing a mutable OpenClaw config, prepare a batch file like this: ```json { @@ -148,7 +147,8 @@ After testing, persist the working provider through `nemoclaw onboard` so the sa ## Verify the Fix -After switching to vLLM, ask for an action that should use a tool. Good signs: +After switching to vLLM, ask for an action that should use a tool. +Look for these signs: - The TUI does not show JSON blobs as assistant text. - The gateway log shows tool dispatch and a follow-up answer. diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index a117a6c3452..67f4a070a72 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -23,10 +23,10 @@ OpenShell intercepts inference traffic and forwards it to the local endpoint you ## Prerequisites -- NemoClaw installed. Refer to the [Quickstart](../get-started/quickstart) if you have not installed yet. +- NemoClaw installed. Refer to the [Quickstart](../get-started/quickstart) if you have not installed NemoClaw yet. -- NemoClaw installed. Refer to [Quickstart with Hermes](../get-started/quickstart) if you have not installed yet. +- NemoClaw installed. Refer to [Quickstart with Hermes](../get-started/quickstart) if you have not installed NemoClaw yet. - A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install. @@ -37,8 +37,10 @@ The onboard wizard detects Ollama automatically when you have installed it or st 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. +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. +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`). +The upgrade entry still appears when only one side is stale, for example a fresh user-local binary paired with the original system daemon. The gate skips Windows-host Ollama reached from WSL through `host.docker.internal`. The separate **Use / Start / Install Ollama on Windows host** entries handle that case and run their own actions on the Windows side. On macOS, the wizard runs the platform install or upgrade path with `brew upgrade ollama`. @@ -64,9 +66,11 @@ Override the detection with `NEMOCLAW_OLLAMA_INSTALL_MODE=system` or `NEMOCLAW_O The user-local install replicates only the binary extraction step of the official installer. It downloads the release tarball, extracts it to `${HOME}/.local`, and launches `${HOME}/.local/bin/ollama serve` one time. It does not configure a systemd service, does not create the `ollama` system user, and does not install CUDA drivers, so you must relaunch the daemon manually after a reboot. -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. +NemoClaw also prints a one-line `PATH` hint if `${HOME}/.local/bin` is not already on your `PATH`. +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. +Both modes rely on `zstd` for archive extraction. +On Debian and Ubuntu, the system path uses `sudo apt-get` to install `zstd` automatically and explains the prompt before continuing. The user-local path cannot bootstrap system packages without elevation. If `zstd` is missing, it prints per-distro install hints and exits. Install `zstd` manually, then rerun onboarding. @@ -111,11 +115,9 @@ Selecting one of those actions in the unsupported native Docker topology exits e -Ollama is convenient for local chat, but some model/template combinations can -return tool calls as plain text under realistic agent load. If the TUI shows raw -JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a -tool, switch to vLLM with `--enable-auto-tool-choice` and the correct -`--tool-call-parser`. See [Tool-Calling Reliability](tool-calling-reliability). +Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load. +If the TUI shows raw JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a tool, switch to vLLM with `--enable-auto-tool-choice` and the correct `--tool-call-parser`. +See [Tool-Calling Reliability](tool-calling-reliability). @@ -131,14 +133,12 @@ Windows-host Ollama uses the Windows daemon through `host.docker.internal`. For non-WSL Ollama setups, the onboard wizard manages the proxy automatically: -- Generates a random 24-byte token on first run and stores it in - `~/.nemoclaw/ollama-proxy-token` with `0600` permissions. +- Generates a random 24-byte token on first run and stores it in `~/.nemoclaw/ollama-proxy-token` with `0600` permissions. - Starts the proxy after Ollama and verifies it before continuing. - Cleans up stale proxy processes from previous runs. - Probes the sandbox Docker network path to the proxy before committing the inference route. - Stops matching proxy processes during uninstall before deleting NemoClaw state. -- Reuses the persisted token after a host reboot so you do not need to re-run - onboard. +- Reuses the persisted token after a host reboot so you do not need to re-run onboard. On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge. When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like: @@ -154,12 +154,11 @@ NemoClaw configures the sandbox provider to use proxy port `11435` with the gene OpenShell's L7 proxy injects the token at egress, so the agent inside the sandbox never sees the token directly. All proxy endpoints require the Bearer token, including `GET /api/tags`. -Internal health and reachability checks run through the proxy treat any HTTP response, including `401`, as proof the proxy is alive. +Internal health and reachability checks that 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 -path to the model server. +If Ollama is already running on a non-loopback address when you start onboard, the wizard restarts it on `127.0.0.1:11434`. +The proxy becomes the only network path to the model server. ### GPU Memory Cleanup @@ -177,7 +176,8 @@ NEMOCLAW_PROVIDER=ollama \ If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. -Unknown or custom tags (any value the bootstrap registry has not seen) are still passed through; the Ollama runner validates the choice itself. +Unknown or custom tags, meaning any value the bootstrap registry has not seen, still pass through. +The Ollama runner validates the choice itself. In interactive onboarding, registry-known installed tags that do not fit current GPU memory are filtered out of the installed-model menu. If none of the installed registry-known tags fit, NemoClaw shows the starter-model choices and warns when even the smallest bootstrap tag may not fit. After a selected model fails validation, NemoClaw excludes that tag from the next installed-model menu so pressing Enter cannot select the same failing model repeatedly. @@ -234,7 +234,7 @@ If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding ## Switch Models at Runtime -You can change the model without re-running onboard. +Change the model without re-running onboard. Refer to [Switch Inference Models](switch-inference-providers) for the full procedure. For compatible endpoints, the command is: diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index 0d9b5c558ad..68cfc25fb80 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -3,8 +3,8 @@ # SPDX-License-Identifier: Apache-2.0 title: "Backup and Restore Workspace Files" sidebar-title: "Backup and Restore" -description: "How to back up and restore OpenClaw workspace files before destructive operations." -description-agent: "Backs up and restores OpenClaw workspace files before destructive operations such as sandbox rebuilds. Use when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds." +description: "How to back up and restore sandbox workspace and state files before destructive operations." +description-agent: "Backs up and restores sandbox workspace and state files before destructive operations such as sandbox rebuilds. Use when downloading workspace files from a sandbox, uploading restored files into a new sandbox, or preserving sandbox state across rebuilds." keywords: ["nemoclaw backup", "nemoclaw restore", "workspace backup", "openshell sandbox download upload"] content: type: "how_to" @@ -14,7 +14,7 @@ skill: import { AgentOnly } from "../_components/AgentGuide"; Workspace and state files define your agent's personality, memory, user context, and durable runtime state. -They persist across sandbox restarts, but destroying the sandbox **permanently deletes** them. +They persist across sandbox restarts, but destroying the sandbox permanently deletes them. This guide covers snapshot commands, all-sandbox backups, and manual backup with CLI commands. @@ -22,26 +22,27 @@ This guide covers snapshot commands, all-sandbox backups, and manual backup with -- Before running `$$nemoclaw destroy` -- Before major NemoClaw version upgrades -- Periodically, if you've invested time customizing your agent +- Before running `$$nemoclaw destroy`. +- Before major NemoClaw version upgrades. +- Periodically, if you have invested time customizing your agent. -- Before running `$$nemoclaw destroy` -- Before major NemoClaw version upgrades -- Periodically, if you've invested time customizing your agent or paired messaging channels +- Before running `$$nemoclaw destroy`. +- Before major NemoClaw version upgrades. +- Periodically, if you have invested time customizing your agent or paired messaging channels. ## Snapshot Commands -The fastest way to back up and restore sandbox state is with the built-in snapshot commands. +Use the built-in snapshot commands for the fastest backup and restore path. Snapshots capture all workspace state directories defined in the agent manifest and store them in `~/.nemoclaw/rebuild-backups//`. Agent manifests can also declare durable top-level state files. For Hermes, snapshots include `SOUL.md` and the SQLite database behind `.hermes/state.db` using SQLite's online backup API, then restore that database through SQLite instead of copying a live raw database file. -Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore. +Treat snapshot directories as private local data. +The Hermes database can contain session metadata and message history needed for a faithful restore. Snapshots also preserve sandbox registry metadata that affects rebuild behavior, including custom policy presets applied with `policy-add --from-file` or `policy-add --from-dir`. When you restore a snapshot, NemoClaw replays those recorded custom presets with their stored YAML content, so you do not need the original preset files on disk for the restored sandbox to keep the same policy state. @@ -90,10 +91,9 @@ If the restored config cannot be parsed or applied safely, NemoClaw stops the re The `$$nemoclaw rebuild` command uses the same snapshot mechanism automatically. NemoClaw rejects unsafe symlinks and hard links inside sandbox state during backup creation before they can enter a snapshot. -Credential-bearing Hermes files such as `auth.json` are intentionally excluded -from snapshots. NemoClaw-regenerated Hermes config files (`config.yaml` and -`.env`) are also excluded; model/provider and messaging credentials are -recreated from host-side onboarding and OpenShell provider state during rebuild. +Credential-bearing Hermes files such as `auth.json` are intentionally excluded from snapshots. +NemoClaw-regenerated Hermes config files, including `config.yaml` and `.env`, are also excluded. +NemoClaw recreates model/provider and messaging credentials from host-side onboarding and OpenShell provider state during rebuild. For full details, see the [Commands reference](../reference/commands). @@ -166,15 +166,15 @@ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/pl ## Back Up All Running Sandboxes -To back up every registered, running sandbox in one step, run `nemoclaw backup-all`. -This is the recommended host-installed command before broad maintenance such as `nemoclaw update`, `nemoclaw upgrade-sandboxes`, or an OpenShell gateway migration. +To back up every registered, running sandbox in one step, run `$$nemoclaw backup-all`. +Use this host-installed command before broad maintenance such as `$$nemoclaw update`, `$$nemoclaw upgrade-sandboxes`, or an OpenShell gateway migration. ```bash $$nemoclaw backup-all ``` `backup-all` walks the sandboxes registered on the host, creates a snapshot for each running sandbox, and stores the snapshot bundles under `~/.nemoclaw/rebuild-backups//`. -Use `nemoclaw snapshot list` and `nemoclaw snapshot restore` to inspect or restore one sandbox's bundles later. +Use `$$nemoclaw snapshot list` and `$$nemoclaw snapshot restore` to inspect or restore one sandbox's bundles later. ## Using the Backup Script @@ -252,10 +252,9 @@ 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`. -### Shared files across agents +### 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. +Files that operators typically want consistent across every per-agent workspace, such as `AGENTS.md`, shared skills, and common templates, are not synced automatically. Each workspace is independent, and changes in one do not propagate. Operators that need this either copy the shared files explicitly to each workspace after editing or maintain a host-side sync layer. NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). @@ -274,4 +273,4 @@ Refer to [Workspace Files](workspace-files) for the Hermes state layout. ## Next Steps - [Workspace Files overview](workspace-files) to learn what each file does. -- [Commands reference](../reference/commands) +- [Commands reference](../reference/commands). diff --git a/docs/manage-sandboxes/install-plugins-hermes.mdx b/docs/manage-sandboxes/install-plugins-hermes.mdx index 08ece9dca02..322db32eb76 100644 --- a/docs/manage-sandboxes/install-plugins-hermes.mdx +++ b/docs/manage-sandboxes/install-plugins-hermes.mdx @@ -25,7 +25,7 @@ Do not replace or remove `/sandbox/.hermes/plugins/nemoclaw` when you add your o ## Choose an Install Path -Today, the supported path for custom Hermes plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. +The supported path for custom Hermes plugins is to bake the plugin into a custom sandbox image and onboard from that Dockerfile. Use this path when the plugin adds Python code, runtime hooks, or dependencies that Hermes must see at gateway startup. `nemohermes skill install ` is only for `SKILL.md` agent skills. @@ -33,7 +33,7 @@ It uploads skill instructions and refreshes skill discovery, but it does not ins ## Prepare a Build Directory -Put the custom Dockerfile and everything it needs to `COPY` in one directory. +Put the custom Dockerfile and every file it needs to `COPY` in one directory. `nemohermes onboard --from ` sends the Dockerfile's parent directory as the Docker build context. Add a `.dockerignore` next to the Dockerfile to keep local caches, generated artifacts, model files, or other unneeded paths out of the staged context. NemoClaw still excludes credential-like paths such as `.env*`, `.ssh/`, `.aws/`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`, even if `.dockerignore` tries to include them. @@ -51,7 +51,8 @@ The image must still include the generated Hermes config, NemoClaw Hermes plugin A custom `--from` Dockerfile replaces the normal NemoClaw Hermes Dockerfile. - Starting from `ghcr.io/nvidia/nemoclaw/hermes-sandbox-base:latest` alone is not enough unless your Dockerfile also preserves the NemoClaw Hermes layers from `agents/hermes/Dockerfile`. + Starting from `ghcr.io/nvidia/nemoclaw/hermes-sandbox-base:latest` alone is not enough. + Your Dockerfile must also preserve the NemoClaw Hermes layers from `agents/hermes/Dockerfile`. ## Install the Plugin in the Image @@ -107,12 +108,12 @@ 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, refer to [Network Policies](../reference/network-policies). -For custom preset workflows, refer to [Customize Network Policy](../network-policy/customize-network-policy). +See [Network Policies](../reference/network-policies) for policy concepts. +See [Customize Network Policy](../network-policy/customize-network-policy) for custom preset workflows. ## Common Mistakes -These are the most common places where Hermes plugin installation gets mixed up with other NemoClaw extension paths. +The following places commonly mix Hermes plugin installation with other NemoClaw extension paths. - Do not use `skill install` for Hermes runtime plugins. - Do not install Hermes plugins into `/sandbox/.openclaw/extensions`; that path is for OpenClaw plugins. diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 90b021d7045..0f746805fca 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -19,7 +19,7 @@ Use this guide after you finish the [OpenClaw quickstart](../get-started/quickst Use this guide after you finish [Quickstart with Hermes](../get-started/quickstart). -It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. +It covers ongoing sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw` and `openshell`. @@ -95,7 +95,7 @@ The debug command gathers system information, Docker state, gateway logs, and sa ## Manage Dashboard Ports -If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart it manually with the port from the install summary. +If the forward stopped, or the installer reported that no active forward was found and the URL does not load, restart the forward manually with the port from the install summary. ```bash openshell forward start --background my-gpt-claw @@ -109,7 +109,7 @@ openshell forward list ## Run Multiple Sandboxes -Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. +Each sandbox needs its own dashboard port because `openshell forward` refuses to bind a port that another sandbox already uses. When the default port is already held by another sandbox, `$$nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. @@ -153,7 +153,7 @@ Change the active model or provider at runtime without rebuilding the sandbox: $$nemoclaw inference set --model --provider ``` -Refer to [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. +See [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward @@ -170,7 +170,7 @@ $$nemoclaw recover The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step. It is idempotent and safe to script. -Refer to [`$$nemoclaw recover`](../reference/commands#$$nemoclaw-name-recover) for details. +See [`$$nemoclaw recover`](../reference/commands#$$nemoclaw-name-recover) for details. ### Reset a Stored Credential @@ -182,7 +182,7 @@ $$nemoclaw credentials reset # clear a single provider, for exampl $$nemoclaw onboard # re-run to re-enter the cleared provider ``` -The command reference documents [`$$nemoclaw credentials reset `](../reference/commands#$$nemoclaw-credentials-reset-provider) in full. +See [`$$nemoclaw credentials reset `](../reference/commands#$$nemoclaw-credentials-reset-provider) for full command details. ### Rebuild a Sandbox While Preserving Workspace State @@ -197,19 +197,19 @@ If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a $$nemoclaw rebuild ``` -Rebuild preserves the mounted workspace and registered policies while recreating the container. +The rebuild command preserves the mounted workspace and registered policies while recreating the container. If NemoClaw cannot archive any requested state path, it reports the backup failure and stops before deleting the original sandbox. -Refer to [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for flag details. +See [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for flag details. ### Add a Network Preset After Onboarding -Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding: +Apply an additional preset, such as Telegram or GitHub, to a running sandbox without running onboarding again: ```bash $$nemoclaw policy-add ``` -Refer to [`$$nemoclaw policy-add`](../reference/commands#$$nemoclaw-name-policy-add) for usage details and flags. +See [`$$nemoclaw policy-add`](../reference/commands#$$nemoclaw-name-policy-add) for usage details and flags. Non-interactive re-onboards in the default `suggested` policy mode preserve presets added this way. To make a re-onboard authoritative, set `NEMOCLAW_POLICY_MODE=custom` and provide `NEMOCLAW_POLICY_PRESETS` with the exact list to apply; onboarding removes anything else. @@ -239,8 +239,8 @@ Each rebuild destroys the old container and creates a new one, while preserving `upgrade-sandboxes --check` can report a sandbox as stale because the running agent version is behind, because the managed NemoClaw image fingerprint differs from the current CLI, or both. Custom-image sandboxes created with `--from ` are not marked stale solely by image fingerprint, so an upgrade check does not accidentally replace them with the default image. Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved. -For the full state-preservation contract, snapshot restore behavior, and manual backup workflow, refer to [Backup and Restore](backup-restore). -For command flags, refer to [`$$nemoclaw update`](../reference/commands#$$nemoclaw-update), [`$$nemoclaw upgrade-sandboxes`](../reference/commands#$$nemoclaw-upgrade-sandboxes), and [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild). +See [Backup and Restore](backup-restore) for the full state-preservation contract, snapshot restore behavior, and manual backup workflow. +See [`$$nemoclaw update`](../reference/commands#$$nemoclaw-update), [`$$nemoclaw upgrade-sandboxes`](../reference/commands#$$nemoclaw-upgrade-sandboxes), and [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for command flags. ## Uninstall @@ -257,7 +257,7 @@ $$nemoclaw uninstall | `--delete-models` | Also remove NemoClaw-pulled Ollama models. | -The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots that snapshot and `backup-all` commands write), `~/.nemoclaw/backups/` (workspace backups that `scripts/backup-workspace.sh` writes), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default. +The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots written by snapshot and `backup-all` commands), `~/.nemoclaw/backups/` (workspace backups written by `scripts/backup-workspace.sh`), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default. Uninstall removes every other entry under `~/.nemoclaw/`. Interactive runs prompt before they remove the preserved entries; the default answer keeps them. For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well. @@ -278,7 +278,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, refer to [`$$nemoclaw uninstall` vs. the hosted `uninstall.sh`](../reference/commands#$$nemoclaw-uninstall-vs-the-hosted-uninstallsh). +See [`$$nemoclaw uninstall` vs. the hosted `uninstall.sh`](../reference/commands#$$nemoclaw-uninstall-vs-the-hosted-uninstallsh) for a full comparison of what the two forms fetch, what they trust, and when to prefer each. ## Related Topics diff --git a/docs/manage-sandboxes/messaging-channels.mdx b/docs/manage-sandboxes/messaging-channels.mdx index bcab813b198..c6053a9b918 100644 --- a/docs/manage-sandboxes/messaging-channels.mdx +++ b/docs/manage-sandboxes/messaging-channels.mdx @@ -13,16 +13,17 @@ skill: --- import { AgentOnly } from "../_components/AgentGuide"; -Telegram, Discord, Slack, WeChat, WhatsApp, and Microsoft Teams reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs. +Telegram, Discord, Slack, WeChat, WhatsApp, and Microsoft Teams reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway resources. For token-based channels, NemoClaw registers credentials with OpenShell providers. -WeChat captures a token through a host-side QR scan during onboarding. +WeChat uses a host-side QR scan during onboarding to capture a token. WhatsApp pairs inside the sandbox through a QR scan and intentionally stores mutable session state there. Microsoft Teams uses Bot Framework credentials plus a public HTTPS webhook that forwards to the sandbox. -NemoClaw bakes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control. +NemoClaw writes the selected channel configuration into the sandbox image and keeps runtime delivery under OpenShell control. WeChat, WhatsApp, and Microsoft Teams are experimental. -WeChat and WhatsApp rely on QR-based pairing flows that are more fragile than token-based bots, and Microsoft Teams requires an externally reachable webhook path that depends on your host networking setup. +WeChat and WhatsApp rely on QR-based pairing flows that are more fragile than token-based bots. +Microsoft Teams requires an externally reachable webhook path that depends on your host networking setup. Interfaces, defaults, and supported features can change, and NVIDIA does not recommend these channels for production use. @@ -43,12 +44,13 @@ It only starts optional host services such as the cloudflared tunnel when that b `$$nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. It only starts optional host services such as the cloudflared tunnel when that binary is present. -For details, refer to [Commands](../reference/commands). +See [Commands](../reference/commands) for details. ## Prerequisites - A machine where you can run `$$nemoclaw onboard` (local or remote host that runs the gateway and sandbox). -- A token or app credential set for each credential-based messaging platform you want to enable, a personal WeChat account on your phone for the host-side QR scan during onboarding, or a phone you can use to scan the QR code for WhatsApp pairing. +- A token or app credential set for each credential-based messaging platform you want to enable. +- A personal WeChat account on your phone for the host-side QR scan during onboarding, or a phone you can use to scan the QR code for WhatsApp pairing. - A network policy preset for each enabled channel, or equivalent custom egress rules. ## Channel Requirements @@ -67,7 +69,7 @@ Open Telegram, send `/newbot` to [@BotFather](https://t.me/BotFather), follow th For Telegram group chats, disable privacy mode before testing group replies: in @BotFather, run `/setprivacy`, choose the bot, then choose **Disable**. After changing privacy mode, remove the bot from each Telegram group and add it back so Telegram applies the new delivery setting to that group. `TELEGRAM_ALLOWED_IDS` is a comma-separated list of Telegram user or private-chat IDs for DM access. -For compatibility with older QA scripts, NemoClaw also treats `TELEGRAM_AUTHORIZED_CHAT_IDS` and `TELEGRAM_CHAT_ID` as aliases, but new automation should use `TELEGRAM_ALLOWED_IDS`. +For compatibility with older QA scripts, NemoClaw also accepts `TELEGRAM_AUTHORIZED_CHAT_IDS` and `TELEGRAM_CHAT_ID` as aliases, but new automation should use `TELEGRAM_ALLOWED_IDS`. Keep these aliases until QA automation and public repro templates have stopped exporting them for at least one full release. Group chats stay open by default so rebuilt sandboxes do not silently drop Telegram group messages because of an empty group allowlist. NemoClaw defaults `TELEGRAM_GROUP_POLICY` to `open` for OpenClaw. @@ -88,9 +90,10 @@ NemoClaw routes Discord REST and gateway traffic through the top-level managed p Slack uses Socket Mode and requires two tokens. Use `SLACK_BOT_TOKEN` for the bot user OAuth token (`xoxb-...`) and `SLACK_APP_TOKEN` for the app-level Socket Mode token (`xapp-...`). NemoClaw validates both tokens before it saves Slack credentials or enables the channel. -This validation calls the live Slack API (`auth.test` and `apps.connections.open`), so the tokens must belong to a real Slack app. +This validation calls the live Slack APIs `auth.test` and `apps.connections.open`, so the tokens must belong to a real Slack app. If Slack rejects the tokens (for example, `invalid_auth` for placeholder or fake values), NemoClaw skips the Slack channel. -Because the `slack` network policy preset is only applied for channels that are actually enabled, a skipped Slack channel also means the `slack` preset is not applied, so it does not appear as applied (`●`) in `$$nemoclaw policy-list`. +NemoClaw applies the `slack` network policy preset only for channels that are actually enabled. +When Slack is skipped, NemoClaw does not apply the `slack` preset, so it does not appear as applied (`●`) in `$$nemoclaw policy-list`. To exercise Slack channel setup and the `slack` policy preset with placeholder tokens in a restricted network or hermetic test environment, set `NEMOCLAW_SKIP_SLACK_AUTH_VALIDATION=1` to skip the live credential probes; Slack token format checks still apply. Set `SLACK_ALLOWED_USERS` to comma-separated Slack member IDs to authorize those users for DMs and for channel `@mention` events in channels where the Slack app is present. Set `SLACK_ALLOWED_CHANNELS` to comma-separated Slack channel IDs to restrict channel `@mention` handling to those channels. @@ -191,7 +194,8 @@ Then run onboarding: $$nemoclaw onboard ``` -Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `-telegram-bridge`, `-teams-bridge`, or `-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. +Complete the rest of the wizard so the blueprint can create OpenShell providers where needed, such as `-telegram-bridge`, `-teams-bridge`, or `-wechat-bridge`. +The wizard also writes channel configuration into the image through `NEMOCLAW_MESSAGING_CHANNELS_B64` and starts the sandbox. ## Add Channels After Onboarding @@ -213,14 +217,16 @@ $$nemoclaw my-assistant channels add whatsapp $$nemoclaw my-assistant channels add teams ``` -`channels add` collects whatever each channel needs. +`channels add` collects the inputs each channel needs. It prompts for Telegram, Discord, Slack, and Microsoft Teams tokens and configuration, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild. It registers bridge providers with the OpenShell gateway when it captures tokens, records the channel in the sandbox registry, and asks whether to rebuild immediately. 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 apply step 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. +It then exits without prompting for a rebuild. +If any gateway-side step, such as provider detach or delete, fails, the rollback continues and prints a `Rollback could not fully clean ` warning so you can clean up manually. When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers. It flags `gateway-providers` as residual because the in-flight upsert can leave the gateway with the new token. Verify the gateway bridge before relying on the channel. diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx index a50ccdfd837..fb5608a168a 100644 --- a/docs/manage-sandboxes/runtime-controls.mdx +++ b/docs/manage-sandboxes/runtime-controls.mdx @@ -17,8 +17,8 @@ This page explains which parts of a running NemoClaw sandbox can change immediat ## What You Can Change at Runtime -NemoClaw applies its security posture in three layers: what onboarding bakes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard. -The table below maps each commonly changed item to the layer that owns it and the command that changes it. +NemoClaw applies its security posture in three layers: what onboarding writes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard. +This table maps each commonly changed item to the layer that owns it and the command that changes it. @@ -61,16 +61,14 @@ If a row above conflicts with what you observe, the runtime source of truth insi | GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | | Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `$$nemoclaw inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | -If a row above conflicts with what you observe, the runtime source of truth for -Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`; the host -registry caches metadata but the image and Hermes runtime read from the -in-sandbox files. +If a row above conflicts with what you observe, the runtime source of truth for Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`. +The host registry caches metadata, but the image and Hermes runtime read from the in-sandbox files. ## See Also -The mutability table above is a consolidated index of information that lives in more detail on per-topic pages: +The table above consolidates details from these topic pages: diff --git a/docs/manage-sandboxes/workspace-files.mdx b/docs/manage-sandboxes/workspace-files.mdx index a7d5b4e6423..81682365f1a 100644 --- a/docs/manage-sandboxes/workspace-files.mdx +++ b/docs/manage-sandboxes/workspace-files.mdx @@ -46,9 +46,8 @@ All workspace files reside inside the sandbox filesystem: ## Multi-Agent Deployments A single NemoClaw sandbox can host more than one OpenClaw agent. -When you configure OpenClaw with multiple named agents (for example, a shared `main` agent -plus per-user agents for a Teams-integrated deployment), each agent gets its own -workspace directory alongside the default `workspace/`: +When you configure OpenClaw with multiple named agents, each agent gets its own workspace directory alongside the default `workspace/`. +For example, a Teams-integrated deployment can use a shared `main` agent plus per-user agents. ```text /sandbox/.openclaw/ @@ -58,17 +57,16 @@ workspace directory alongside the default `workspace/`: └── workspace-ops/ # named agent "ops" ``` -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 -`workspace-support/`. +Each per-agent workspace contains the same Markdown file structure as the default workspace: `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `MEMORY.md`, and `memory/`. +Files are per-agent. +Changes in `workspace-main/AGENTS.md` are not visible to `workspace-support/`. -NemoClaw handles persistence and snapshots automatically for per-agent workspaces: -the sandbox entrypoint provisions each `workspace-/` directly under the writable `.openclaw/` tree so state survives sandbox restart, and `$$nemoclaw snapshot create` discovers every `workspace-/` directory and includes it in the snapshot bundle alongside the default `workspace/`. +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. +`$$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. +Files that operators typically want consistent across every agent workspace, such as `AGENTS.md`, shared skills, and common templates, are not synced automatically. Each workspace is independent, and changes in one do not propagate. NVIDIA tracks shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). @@ -114,8 +112,10 @@ You can edit them in two ways: -Hermes stores durable agent state under `/sandbox/.hermes/` instead of the OpenClaw workspace directory. -The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environment settings live in `/sandbox/.hermes/.env`, and runtime state such as logs, memory, platform sessions, and the SQLite state database lives under the same `.hermes` tree. +Hermes stores durable agent state under `/sandbox/.hermes/`, not in the OpenClaw workspace directory. +The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`. +Environment settings live in `/sandbox/.hermes/.env`. +Runtime state, such as logs, memory, platform sessions, and the SQLite state database, lives under the same `.hermes` tree. ## Important Hermes State @@ -130,7 +130,7 @@ The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environme ## Persistence Behavior -Hermes state lives in the sandbox's persistent state volume, not only in the container image. +Hermes state lives in the sandbox's persistent state volume, not in the container image alone. Normal restarts preserve that state. Rebuilds and upgrades use NemoClaw's snapshot flow to preserve manifest-defined Hermes state, including `SOUL.md` and the SQLite database behind `.hermes/state.db`. diff --git a/docs/monitoring/monitor-sandbox-activity.mdx b/docs/monitoring/monitor-sandbox-activity.mdx index 336ddb5c215..cd4bbe46281 100644 --- a/docs/monitoring/monitor-sandbox-activity.mdx +++ b/docs/monitoring/monitor-sandbox-activity.mdx @@ -13,7 +13,7 @@ skill: --- import { AgentOnly } from "../_components/AgentGuide"; -Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems. +Use NemoClaw status commands, log streams, and OpenShell TUI views to inspect sandbox health, trace agent behavior, and diagnose problems. ## Prerequisites @@ -22,20 +22,20 @@ Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, ## Check Sandbox Health -Run the status command to view the sandbox state, gateway health, and active inference configuration: +Run the status command to view sandbox state, gateway health, and the active inference configuration. ```bash $$nemoclaw status ``` -For local Ollama and local vLLM routes, `$$nemoclaw status` also probes the host-side health endpoint directly. -This check catches a stopped local backend before you retry `inference.local` from inside the sandbox. +For local Ollama and local vLLM routes, `$$nemoclaw status` also probes the host-side health endpoint. +The check catches a stopped local backend before you retry `inference.local` from inside the sandbox. -Key output fields include: +Review these output fields. - 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. +- Gateway and process health show whether NemoClaw can 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` 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. @@ -43,13 +43,13 @@ Use `openshell sandbox list` for the underlying sandbox details. ## View Blueprint and Sandbox Logs -Stream the most recent log output from the blueprint runner and sandbox: +Stream recent log output from the blueprint runner and sandbox. ```bash $$nemoclaw logs ``` -To follow the log output in real time: +Follow log output in real time. ```bash $$nemoclaw logs --follow @@ -61,32 +61,32 @@ It does not export the structured per-session agent state that OpenClaw stores u ## Inspect Agent Session State OpenClaw stores structured session state inside the sandbox. -Use these files when you need an audit trail, a compliance review surface, or replay tooling that includes assistant messages and tool activity. +Use these files for audit trails, compliance review, or replay tooling that includes assistant messages and tool activity. | File | Purpose | |---|---| -| `/sandbox/.openclaw/agents/main/sessions/.jsonl` | Per-session event log. Use this file for audit trails and compliance dashboards. Records can include assistant messages, `thinking` blocks, tool calls, tool results, token usage, and cost metadata. | -| `/sandbox/.openclaw/agents/main/sessions/.trajectory.jsonl` | Lower-level trajectory data for fine-grained replay. This file can be large, so avoid using it for routine audit summaries. | +| `/sandbox/.openclaw/agents/main/sessions/.jsonl` | Per-session event log for audit trails and compliance dashboards that can include assistant messages, `thinking` blocks, tool calls, tool results, token usage, and cost metadata. | +| `/sandbox/.openclaw/agents/main/sessions/.trajectory.jsonl` | Lower-level trajectory data for fine-grained replay that can be large, so avoid it for routine audit summaries. | | `/sandbox/.openclaw/agents/main/sessions/sessions.json` | Session index that maps known session keys to their persisted state. | -To inspect the session directory from the host, run a sandbox command: +Inspect the session directory from the host by running a sandbox command. ```bash $$nemoclaw sandbox exec -- ls -lh /sandbox/.openclaw/agents/main/sessions ``` -To copy a session log for offline review, use the OpenShell sandbox download command: +Copy a session log for offline review with the OpenShell sandbox download command. ```bash openshell sandbox download /sandbox/.openclaw/agents/main/sessions/.jsonl . ``` -Treat exported session logs as sensitive data. +Handle exported session logs as sensitive data. They can contain prompts, tool inputs, tool outputs, file paths, and cost metadata from the agent run. ## Monitor Network Activity in the TUI -Open the OpenShell terminal UI for a live view of sandbox network activity and egress requests: +Open the OpenShell terminal UI to view sandbox network activity and egress requests live. ```bash openshell term @@ -94,17 +94,17 @@ openshell term For a remote sandbox, SSH to the instance and run `openshell term` there. -The TUI shows the following information: +The TUI shows these signals. - Active network connections from the sandbox. - Blocked egress requests awaiting operator approval. - Inference routing status. -Refer to [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests) for details on handling blocked requests. +See [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests) for details about handling blocked requests. ## Test Inference -Run a test inference request to verify that the provider is responding: +Send a test inference request to verify that the provider responds. ```bash @@ -119,13 +119,13 @@ hermes ``` -If the request fails, check the following: +If the request fails, check these items. 1. Run `$$nemoclaw status` to confirm the active provider and endpoint. For local Ollama and local vLLM, check the `Inference` line first. If it shows `unreachable`, restart the local backend before retrying from inside the sandbox. 2. Run `$$nemoclaw logs --follow` to view error messages from the blueprint runner. -3. Verify that the inference endpoint is reachable from the host. +3. Verify that the host can reach the inference endpoint. ## Related Topics diff --git a/docs/network-policy/approve-network-requests.mdx b/docs/network-policy/approve-network-requests.mdx index 4e86a47e919..a343f166ebc 100644 --- a/docs/network-policy/approve-network-requests.mdx +++ b/docs/network-policy/approve-network-requests.mdx @@ -11,8 +11,8 @@ content: skill: priority: 20 --- -Review and act on network requests that the agent makes to endpoints not listed in the sandbox policy. -OpenShell intercepts these requests and presents them in the TUI for operator approval. +Review network requests that the agent makes to endpoints that are not listed in the sandbox policy. +OpenShell intercepts those requests and presents them in the TUI for operator approval. ## Prerequisites @@ -46,39 +46,39 @@ openshell term -The TUI displays the sandbox state, active inference provider, and a live feed of network activity. +The TUI shows the sandbox state, active inference provider, and live network activity. ## Trigger a Blocked Request -When the agent attempts to reach an endpoint that is not in the baseline policy, OpenShell blocks the connection and displays the request in the TUI. +When the agent tries to reach an endpoint that is not in the baseline policy, OpenShell blocks the connection and displays the request in the TUI. The blocked request includes the following details: -- **Host and port** of the destination. +- **Host and port** for the destination. - **Binary** that initiated the request. - **HTTP method** and path, if available. ## Approve or Deny the Request -The TUI presents an approval prompt for each blocked request. +The TUI shows an approval prompt for each blocked request. -- **Approve** the request to add the endpoint to the running policy for the current session. -- **Deny** the request to keep the endpoint blocked. +- Select **Approve** to add the endpoint to the running policy for the current session. +- Select **Deny** to keep the endpoint blocked. Approved endpoints remain in the running policy until the sandbox stops. They are not persisted to the baseline policy file. -To keep an endpoint allowed after a restart, update the policy YAML or apply a preset as described in [Customize the Sandbox Network Policy](customize-network-policy). +To keep an endpoint allowed after restart, update the policy YAML or apply a preset as described in [Customize the Sandbox Network Policy](customize-network-policy). ## Run the Walkthrough -From the NemoClaw repository root, run the walkthrough script after you have onboarded at least one sandbox and it is reachable: +From the NemoClaw repository root, run the walkthrough script after you onboard at least one sandbox and confirm that it is reachable: ```bash ./scripts/walkthrough.sh ``` -This script opens a split tmux session with the TUI on the left and the agent on the right. +The script opens a split tmux session with the TUI on the left and the agent on the right. The walkthrough requires tmux and the `NVIDIA_INFERENCE_API_KEY` environment variable. -It assumes an existing sandbox to attach to. +It attaches to an existing sandbox. ## Related Topics diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx index 6d03d85711f..a1b605209b7 100644 --- a/docs/network-policy/customize-network-policy.mdx +++ b/docs/network-policy/customize-network-policy.mdx @@ -15,7 +15,7 @@ import { AgentOnly } from "../_components/AgentGuide"; Add, remove, or modify the endpoints the sandbox can reach. -The NemoClaw repository defines the sandbox policy in a declarative YAML file, and [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) enforces it at runtime. +The NemoClaw repository declares the sandbox policy in a 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. @@ -26,8 +26,8 @@ See [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#a -Adding a host to the egress policy permits the connection only after the endpoint, port, method, and binary rules match. -OpenShell still applies SSRF protection separately, so a request can be denied if the final address resolves to a loopback, private, link-local, or otherwise blocked internal range. +Adding a host to the egress policy permits a connection only when the endpoint, port, method, and binary rules match. +OpenShell still applies SSRF protection separately, so it can deny a request when the final address resolves to a loopback, private, link-local, or otherwise blocked internal range. If a package installer or browser runtime download still fails with an SSRF-style denial after you add the public host, install that binary into the sandbox image at build time with [`$$nemoclaw onboard --from`](/reference/commands#--from-dockerfile) instead of relying on runtime egress. @@ -39,7 +39,7 @@ If a package installer or browser runtime download still fails with an SSRF-styl > [!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. -> The sandbox also loses changes made only inside the sandbox when it is recreated. +> The sandbox discards changes made only inside the sandbox when it is recreated. ## Static Changes @@ -50,21 +50,21 @@ Static changes modify the baseline policy file and take effect after the next sa Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. -If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `$$nemoclaw onboard`. +To include a built-in preset in the baseline policy, merge its `network_policies` entries into this file and re-run `$$nemoclaw onboard`. -If you only need to apply a preset to a running sandbox, use `$$nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). +To apply a preset to a running sandbox, use `$$nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit `openclaw-sandbox.yaml`. Open the Hermes policy additions and shared sandbox policy files under `agents/hermes/` and `nemoclaw-blueprint/policies/`, then add or modify endpoint entries. -If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `$$nemoclaw onboard`. +To include a built-in preset in the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `$$nemoclaw onboard`. -If you only need to apply a preset to a running sandbox, use `$$nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). +To apply a preset to a running sandbox, use `$$nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit the baseline policy files. -Use a manual YAML edit when you need to allow custom hosts that are not covered by a preset, such as an internal API or a weather service. +Edit YAML manually when you need to allow custom hosts that a preset does not cover, such as an internal API or a weather service. Each entry in the `network` section defines an endpoint group with the following fields: @@ -97,7 +97,7 @@ $$nemoclaw status ### Add Blueprint Policy Additions -If you maintain a custom blueprint, you can add extra policy entries under `components.policy.additions` in `nemoclaw-blueprint/blueprint.yaml`. +If you maintain a custom blueprint, add extra policy entries under `components.policy.additions` in `nemoclaw-blueprint/blueprint.yaml`. NemoClaw validates those entries with the same policy schema used by preset files, fetches the live policy during sandbox creation, merges the additions into `network_policies`, and applies the merged policy through OpenShell. The applied additions are recorded in the run metadata so you can audit which blueprint-level policy entries were active for that sandbox run. @@ -106,13 +106,14 @@ The applied additions are recorded in the run metadata so you can audit which bl Dynamic changes apply a policy update to a running sandbox without restarting it. > [!WARNING] -> `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge. +> `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide. +> It does not merge. > A running sandbox's live policy is the baseline policy plus every preset that was layered on during onboarding. > Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect. -### Option 1: Drop a Preset File and Use `policy-add` (Recommended) +### Option 1: Add a Preset File and Use `policy-add` (Recommended) -This is the non-destructive path and the only flow NemoClaw supports out of the box for merging new entries into a running policy. +This path preserves existing policy entries and is the only NemoClaw-supported flow for merging new entries into a running policy. 1. Create a preset-format YAML file under `nemoclaw-blueprint/policies/presets/`, for example `nemoclaw-blueprint/policies/presets/influxdb.yaml`: @@ -141,7 +142,7 @@ This is the non-destructive path and the only flow NemoClaw supports out of the $$nemoclaw my-assistant policy-add ``` -NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. +NemoClaw reads the live policy with `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. Existing presets and the baseline remain in place. The preset file under `presets/` also persists across sandbox recreations. @@ -170,13 +171,13 @@ For permanent baseline changes that apply to every future sandbox, edit the sour ### Approve Requests Interactively -For one-off access, you can approve blocked requests in the OpenShell TUI instead of editing the baseline policy: +For one-off access, approve blocked requests in the OpenShell TUI instead of editing the baseline policy: ```bash openshell term ``` -This is useful when you want to test a destination before deciding whether it belongs in a permanent preset or custom policy file. +Use this flow to test a destination before you decide whether it belongs in a permanent preset or custom policy file. ## Policy Presets @@ -256,7 +257,7 @@ See [Commands](../reference/commands#$$nemoclaw-name-policy-add) for the full fl ## Custom Preset Files -Apply a user-authored preset YAML to a running sandbox without editing the baseline or dropping to `openshell policy set`. +Apply a user-authored preset YAML file to a running sandbox without editing the baseline or using `openshell policy set`. ### Authoring @@ -289,7 +290,8 @@ Rename `preset.name` if NemoClaw refuses to apply the file because of a collisio $$nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` -Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. +Use `--dry-run` to preview endpoints without applying changes. +Use `--yes` or export `NEMOCLAW_NON_INTERACTIVE=1` to skip the confirmation prompt. ### Apply Every File in a Directory @@ -297,8 +299,9 @@ Preview the endpoints without applying with `--dry-run`, and skip the confirmati $$nemoclaw my-assistant policy-add --from-dir ./presets/ --yes ``` -Files are processed in lexicographic order. -Processing stops at the first failure; presets already applied are not rolled back. +NemoClaw processes files in lexicographic order. +Processing stops at the first failure. +NemoClaw does not roll back presets that were already applied. Fix the failing file and re-run the command to continue. @@ -309,18 +312,20 @@ Review every host in a custom preset before applying it, especially when the fil ### Remove a Custom Preset NemoClaw records custom presets applied with `--from-file` or `--from-dir` in the sandbox registry alongside their full YAML content. -You can remove them by name without keeping the original file on disk: +Remove them by name without keeping the original file on disk: ```bash $$nemoclaw my-assistant policy-remove my-internal-api --yes ``` -`policy-remove` accepts both built-in and custom preset names. Run `$$nemoclaw policy-list` to see every preset currently applied to the sandbox. +`policy-remove` accepts both built-in and custom preset names. +Run `$$nemoclaw policy-list` to see every preset currently applied to the sandbox. ## Agent Policy Context When an agent runs in the sandbox, it needs a compact view of the active policy so it can decide whether a host or integration is allowed and what to suggest when something fails. -`$$nemoclaw policy-explain` prints that view as a redacted summary: the recorded tier, the applied presets and their allowed host categories, the known presets that are not applied, the inspect/add/remove commands that change policy, and the support boundaries between NemoClaw, OpenShell, and the agent. +`$$nemoclaw policy-explain` prints that view as a redacted summary. +The summary includes the recorded tier, applied presets and their allowed host categories, known presets that are not applied, inspect/add/remove commands that change policy, and support boundaries between NemoClaw, OpenShell, and the agent. ```bash $$nemoclaw my-assistant policy-explain @@ -332,7 +337,8 @@ Pass `--json` to emit the same context as a structured object the agent can read $$nemoclaw my-assistant policy-explain --json ``` -NemoClaw also seeds the rendered context inside the sandbox at `/sandbox/.openclaw/workspace/POLICY.md` once during onboarding and refreshes it on every `policy-add` or `policy-remove`, so the in-sandbox agent picks it up when it scans the workspace. +During onboarding, NemoClaw seeds the rendered context inside the sandbox at `/sandbox/.openclaw/workspace/POLICY.md`. +It refreshes that file on every `policy-add` or `policy-remove`, so the in-sandbox agent picks it up when it scans the workspace. Pass `--write` to refresh that file on demand without changing the policy: ```bash @@ -340,7 +346,8 @@ $$nemoclaw my-assistant policy-explain --write ``` The output is intentionally redacted. -Network policy rule bodies, credential metadata, and binary allowlists are not included; only host stems and category-level summaries appear. +Network policy rule bodies, credential metadata, and binary allowlists are not included. +Only host stems and category-level summaries appear. Host stems that resolve to RFC 1918 ranges (10/8, 172.16/12, 192.168/16), loopback (127/8, `::1`), link-local (169.254/16, `fe80::/10`), cloud metadata (`169.254.169.254`), unique-local IPv6 (`fc00::/7`), reserved zero (0.0.0.0/8), CGNAT (100.64/10), benchmarking (198.18/15), `localhost`, and the internal DNS suffixes `.local`, `.internal`, `.lan`, `.home`, `.home.arpa`, `.corp`, `.intra`, `.intranet`, `.localdomain` are dropped from `allowedHostCategories` and surface as a `redactedHostCount`. Each active preset also carries a `verification` field that tells the agent whether the OpenShell gateway actually enforces it: @@ -348,24 +355,36 @@ Each active preset also carries a `verification` field that tells the agent whet | Status | Meaning | |--------|---------| | `verified` | Registry lists the preset and the gateway confirms it is enforced. Safe to treat the host stems as allowed. | -| `registry-only` | Registry lists the preset but the gateway does not enforce it (drift). Treat allowed hosts as unverified; the agent should not assume the traffic will reach the host. | +| `registry-only` | Registry lists the preset but the gateway does not enforce it (drift). Treat allowed hosts as unverified. The agent should not assume the traffic will reach the host. | | `gateway-only` | Gateway enforces a preset the registry does not list. Reported as active so the agent does not misclassify allowed hosts as blocked. | | `gateway-unavailable` | Could not probe the gateway (no live snapshot). The whole report is advisory; rely on `nemoclaw policy-list` once the gateway is reachable. | The context also documents how the agent should classify a failed host or integration attempt. -The rules are evaluated in order so HTTP 403 has a single interpretation per call: when the host matches an applied preset the request is treated as an authentication failure, otherwise as a policy denial. - -1. `unsupported` — the caller asserts the capability is not offered for this sandbox (for example, a messaging channel that the active agent does not support). The agent should surface the limitation without retrying. -2. `missing-approval` — the host **is** allowed by an applied preset and the request was refused with HTTP 401. The network path is open; credentials are missing or invalid. -3. `missing-approval` (low confidence) — the host **is** allowed by an applied preset and the request was refused with HTTP 403. Ambiguous: OpenShell policies enforce by method, path, protocol, and binary, so a 403 on an allowed host can still be a finer-grained policy denial rather than missing credentials. Confirm credentials first, then run `openshell policy get` to check whether the specific method or path is blocked. -4. `blocked-by-policy` — either the host is **not** allowed by any applied preset and either an existing built-in or custom preset declares it (apply that preset), or the request is refused with a network-block error code (`EHOSTUNREACH`, `ENETUNREACH`, `ENOTFOUND`, `ECONNREFUSED`, `ETIMEDOUT`, `EAI_AGAIN`) or HTTP 403. The same network-block codes also surface as `blocked-by-policy` (low confidence) when the host is on an applied but **unverified** preset (`registry-only` or `gateway-unavailable`), because a block code on a host the registry says should be allowed is the strongest signal that the gateway is not enforcing the preset. -5. `unknown` — none of the above apply; the agent should surface the underlying error. A network-block code on a host that matches a **verified** preset stays `unknown` because the gateway has confirmed enforcement, so the block must be an upstream connectivity failure rather than a policy denial. - -Each classification also carries a `confidence` field set to `high` or `low`. Low-confidence verdicts mean the agent should report multiple possibilities to the user instead of treating the next-step recommendation as authoritative. Common low-confidence triggers are: +The classifier evaluates rules in order so HTTP 403 has a single interpretation per call. +When the host matches an applied preset, the request is treated as an authentication failure. +Otherwise, the request is treated as a policy denial. + +1. `unsupported`: The caller asserts the capability is not offered for this sandbox, such as a messaging channel that the active agent does not support. + The agent should surface the limitation without retrying. +2. `missing-approval`: The host is allowed by an applied preset and the request was refused with HTTP 401. + The network path is open. + Credentials are missing or invalid. +3. `missing-approval` (low confidence): The host is allowed by an applied preset and the request was refused with HTTP 403. + This is ambiguous because OpenShell policies enforce by method, path, protocol, and binary, so a 403 on an allowed host can still be a finer-grained policy denial rather than missing credentials. + Confirm credentials first, then run `openshell policy get` to check whether the specific method or path is blocked. +4. `blocked-by-policy`: Either the host is not allowed by any applied preset and either an existing built-in or custom preset declares it (apply that preset), or the request is refused with a network-block error code (`EHOSTUNREACH`, `ENETUNREACH`, `ENOTFOUND`, `ECONNREFUSED`, `ETIMEDOUT`, `EAI_AGAIN`) or HTTP 403. + The same network-block codes also surface as `blocked-by-policy` (low confidence) when the host is on an applied but unverified preset (`registry-only` or `gateway-unavailable`), because a block code on a host the registry says should be allowed is the strongest signal that the gateway is not enforcing the preset. +5. `unknown`: None of the above apply. + The agent should surface the underlying error. + A network-block code on a host that matches a verified preset stays `unknown` because the gateway has confirmed enforcement, so the block must be an upstream connectivity failure rather than a policy denial. + +Each classification also carries a `confidence` field set to `high` or `low`. +Low-confidence verdicts mean the agent should report multiple possibilities to the user instead of treating the next-step recommendation as authoritative. +Common low-confidence triggers are: - HTTP 403 on an active host (ambiguous between missing credentials and a finer-grained OpenShell denial by method, path, protocol, or binary). -- The matched preset is `registry-only` (the registry lists it but the gateway does not enforce it) — the agent must not assume the host is reachable. -- The matched preset is `gateway-unavailable` (no live gateway snapshot was available) — the verdict is registry-derived and advisory. +- The matched preset is `registry-only` (the registry lists it but the gateway does not enforce it), so the agent must not assume the host is reachable. +- The matched preset is `gateway-unavailable` (no live gateway snapshot was available), so the verdict is registry-derived and advisory. Callers that already hold a verified gateway snapshot can pass it to the classifier so verdicts about hosts on verified presets stay high-confidence. diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 243dd7acac2..1c319f477c0 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -21,7 +21,7 @@ Integration setup usually has two separate parts: - Configure the integration itself, such as a bot token, OAuth credential, or agent plugin setting. - Allow the sandbox to reach the integration's network endpoints through NemoClaw and OpenShell policy. -Prefer NemoClaw commands for policy changes that should be tracked with the sandbox. +Use NemoClaw commands for policy changes that should be tracked with the sandbox. Use OpenShell directly when you need to inspect blocked requests or approve a one-off request in the TUI. ## Before You Start @@ -40,7 +40,7 @@ For a live view of blocked requests, open the OpenShell TUI in a separate host t 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. +When the agent reaches an endpoint that is not in the policy, the TUI shows the host, port, requesting binary, method, and path when available. Approve a request only when you understand why the integration needs it. An approval updates the running policy, but it does not create a reviewable NemoClaw preset entry that `policy-add` can replay. @@ -89,14 +89,14 @@ $$nemoclaw my-assistant policy-remove outlook --yes ## Email and Calendar With Microsoft 365 Use the `outlook` preset for Microsoft 365 email and calendar workflows that use Microsoft Graph or Outlook endpoints. -The preset allows `graph.microsoft.com`, Microsoft login, and Outlook service endpoints. +The preset allows access to `graph.microsoft.com`, Microsoft login, and Outlook service endpoints. ```bash $$nemoclaw my-assistant policy-add outlook --dry-run $$nemoclaw my-assistant policy-add outlook --yes ``` -Then configure the email or calendar tool credentials through the integration you are running in the sandbox. +Configure the email or calendar tool credentials through the integration you run in the sandbox. Keep OAuth client secrets and refresh tokens out of policy files. If the tool still fails, run `openshell term`, trigger the workflow again, and inspect the blocked request. @@ -104,14 +104,14 @@ If the blocked endpoint is not covered by the maintained `outlook` preset, treat ## Telegram Bot Messaging -Telegram needs both channel configuration and egress policy. +Telegram needs channel configuration and egress policy. If you already enabled Telegram during onboarding but did not include the preset, add it to the running sandbox: ```bash $$nemoclaw my-assistant policy-add telegram --yes ``` -To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and make sure the policy preset is applied: +To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and apply the policy preset: ```bash export TELEGRAM_BOT_TOKEN= @@ -130,7 +130,7 @@ The matching preset for each supported messaging channel is the channel name (`t ## Slack or Discord Messaging -Slack and Discord also need both channel configuration and egress policy. +Slack and Discord also need channel configuration and egress policy. Use the matching policy preset after you configure the channel credentials. For Slack: @@ -167,7 +167,7 @@ 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. +A host-side QR scan captures the bot token during onboarding rather than requiring you to paste it from a developer portal. Add the channel interactively and apply the preset: ```bash @@ -194,7 +194,7 @@ $$nemoclaw my-assistant policy-add whatsapp --yes ## GitHub and Jira -Use `github` when the agent needs GitHub API or Git access. +Use `github` when the agent needs GitHub API access or Git access. Use `jira` when the agent needs Atlassian Jira access. Preview first: @@ -214,7 +214,8 @@ $$nemoclaw my-assistant policy-add jira --yes The `jira` preset intentionally allows Node.js access to Atlassian Cloud and does not allow `curl`. When validating it manually, avoid plain `curl -s` against `auth.atlassian.com`. Atlassian can return an empty redirect body even when the request succeeds. -An empty `curl -s` output from that endpoint is inconclusive before or after approval; do not use it as a pass/fail signal. +An empty `curl -s` output from that endpoint is inconclusive before or after approval. +Do not use it as a pass/fail signal. Use a body-visible API probe instead: ```bash @@ -224,7 +225,7 @@ curl -sS --max-time 10 -w '\n%{http_code}\n' https://api.atlassian.com/oauth/tok Before approval, the curl probe should report `000` or a local policy denial. After explicitly approving curl for `api.atlassian.com` in OpenShell, it should return Atlassian's unauthenticated `401` JSON response. -That `401` is the expected success signal for this manual probe. +The `401` response is the expected success signal for this manual probe. This manual probe proves curl reached Atlassian, but no Jira credentials were supplied. Remove access when the task is done: @@ -257,7 +258,7 @@ $$nemoclaw my-assistant policy-add weather --dry-run $$nemoclaw my-assistant policy-add weather --yes ``` -Use the `public-reference` preset when the agent needs read-only public-reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. +Use the `public-reference` preset when the agent needs read-only public reference APIs, such as Wikipedia, Wikidata, Wikimedia Commons, Nominatim, or country metadata. The Open tier includes this preset by default. ```bash @@ -267,7 +268,7 @@ $$nemoclaw my-assistant policy-add public-reference --yes ## Package and Model Tooling -Use these presets when an agent workflow installs packages or downloads model assets: +Use these presets when an agent workflow needs to install packages or download model assets: | Workflow | Preset | |----------|--------| @@ -299,7 +300,7 @@ If `uv` is installed somewhere else in the sandbox, add a custom preset for that ### Homebrew Specifics -The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` preset is the only step needed before installing a formula. +The sandbox base image includes Homebrew (Linuxbrew), so apply the `brew` preset before installing a formula. A `/usr/local/bin/brew` wrapper puts the entry point on the sandbox `PATH` while delegating to the Linuxbrew prefix. Installed formula commands are available from the Linuxbrew bin directory in sandbox shell sessions: @@ -315,9 +316,10 @@ 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 to populate `usage.cost` in session JSONL records. +OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter at startup 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. +The fetch fails closed, and the gateway logs `[gateway/model-pricing] LiteLLM pricing fetch failed: TypeError: fetch failed` and the matching OpenRouter line on every startup. +Every session record sets `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. Apply the `openclaw-pricing` preset to allow both pricing endpoints. @@ -368,7 +370,7 @@ Use OpenShell when you need the full enforced YAML: openshell policy get --full my-assistant > live-policy.yaml ``` -If you must replace the live policy, edit the full policy file and set it back: +If you must replace the live policy, edit the full policy file and apply it back to the sandbox: ```bash openshell policy set --policy live-policy.yaml my-assistant --wait diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index 5e0b89e241e..1c7d23c429a 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -13,7 +13,9 @@ NemoClaw combines a host CLI, an in-sandbox integration layer, and a versioned Y ## System Overview -NVIDIA OpenShell is a general-purpose agent runtime. It provides sandbox containers, a credential-storing gateway, inference proxying, and policy enforcement, but has no opinions about what runs inside. NemoClaw is an opinionated reference stack built on OpenShell that handles what goes in the sandbox, prepares agent-specific integration, and makes the setup accessible. +NVIDIA OpenShell is a general-purpose agent runtime. +It provides sandbox containers, a credential-storing gateway, inference proxying, and policy enforcement, but it has no opinions about what runs inside. +NemoClaw is an opinionated reference stack built on OpenShell that handles what goes in the sandbox, prepares agent-specific integration, and makes the setup accessible. ```mermaid graph LR @@ -208,11 +210,9 @@ flowchart LR ## Sandbox Environment -Normal NemoClaw onboarding builds from the -[`ghcr.io/nvidia/nemoclaw/sandbox-base`](https://github.com/NVIDIA/NemoClaw/pkgs/container/nemoclaw%2Fsandbox-base) -base image and layers the NemoClaw runtime Dockerfile on top. The direct blueprint -runner still carries a pinned OpenShell Community OpenClaw image for legacy -`openshell sandbox create --from` compatibility. Inside the sandbox: +Normal NemoClaw onboarding builds from the [`ghcr.io/nvidia/nemoclaw/sandbox-base`](https://github.com/NVIDIA/NemoClaw/pkgs/container/nemoclaw%2Fsandbox-base) base image and layers the NemoClaw runtime Dockerfile on top. +The direct blueprint runner still carries a pinned OpenShell Community OpenClaw image for legacy `openshell sandbox create --from` compatibility. +Inside the sandbox: - The selected compatible agent runs with the NemoClaw integration layer installed or generated for that agent. - Inference calls are routed through OpenShell to the configured provider. @@ -225,7 +225,7 @@ runner still carries a pinned OpenShell Community OpenClaw image for legacy ## Inference Routing Inference requests from the agent never leave the sandbox directly. -OpenShell intercepts them and routes to the configured provider: +OpenShell intercepts them and routes them to the configured provider: ```text Compatible agent (sandbox) ──▶ OpenShell gateway ──▶ Provider endpoint @@ -242,7 +242,8 @@ Refer to [Inference Options](../inference/inference-options) for provider config ## Provider Credential Storage Provider credentials live in the OpenShell gateway store, not on the host filesystem. -NemoClaw never writes them to host disk; the OpenShell L7 proxy injects values at egress. +NemoClaw never writes them to host disk. +The OpenShell L7 proxy injects values at egress. See [Credential Storage](../security/credential-storage) for the inspection, rotation, and migration flow. ## Host-Side State and Config diff --git a/docs/reference/cli-selection-guide.mdx b/docs/reference/cli-selection-guide.mdx index 21b10dfca15..d1e10bea397 100644 --- a/docs/reference/cli-selection-guide.mdx +++ b/docs/reference/cli-selection-guide.mdx @@ -11,7 +11,7 @@ content: --- NemoClaw uses two host-side CLIs. Use `$$nemoclaw` for NemoClaw-managed workflows. -Use `openshell` when you need a lower-level OpenShell operation that NemoClaw intentionally exposes. +Use `openshell` when you need a lower-level OpenShell operation that NemoClaw intentionally leaves available. ## Rule of Thumb @@ -102,7 +102,7 @@ Use `openshell` when the docs explicitly call for a live OpenShell gateway opera openshell doctor check ``` -- Move files, or run raw one-off commands when you intentionally want to bypass NemoClaw's sandbox registry and wrappers: +- Move files or run raw one-off commands when you intentionally want to bypass NemoClaw's sandbox registry and wrappers: ```bash openshell sandbox upload ./local-file /sandbox/ @@ -149,7 +149,7 @@ The command executes as the sandbox user with `HOME=/sandbox` inside the provisi $$nemoclaw my-assistant exec -- cat /tmp/gateway.log ``` -Use `openshell sandbox exec` for the raw OpenShell execution path, for example when addressing a sandbox by its gateway name or intentionally bypassing the NemoClaw CLI and registry. +Use `openshell sandbox exec` for the raw OpenShell execution path, such as when you address a sandbox by its gateway name or intentionally bypass the NemoClaw CLI and registry. ```bash openshell sandbox exec -n my-assistant -- cat /tmp/gateway.log diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index c8204a1619d..1add6a8251f 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -1766,7 +1766,7 @@ Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-bro ### Onboarding Configuration -These variables let you tune onboarding without editing the Dockerfile or passing repeated flags. +The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags. Set them before running `nemohermes onboard`. | Variable | Format | Effect | @@ -1845,7 +1845,8 @@ The run exits with an actionable diagnostic instead. ### Onboarding Behavior Flags -These flags toggle optional behaviors during onboarding; set them before running `nemohermes onboard`. +The following flags toggle optional behaviors during onboarding. +Set them before running `nemohermes onboard`. | Variable | Format | Effect | |----------|--------|--------| @@ -1912,7 +1913,7 @@ For a remote collector, create a custom preset for the collector host and port i ### Probe Timeouts -These tune how long internal probes wait before giving up. +The following variables tune how long internal probes wait before giving up. Defaults are sized for typical hardware; override only if you see false-positive timeouts. | Variable | Default | Effect | @@ -1943,7 +1944,7 @@ The readiness wait deletes the orphaned sandbox first so the next `nemohermes on ### Lifecycle Behavior Flags -These flags change defaults for commands that manage existing sandboxes. +The following flags change defaults for commands that manage existing sandboxes. | Variable | Format | Effect | |----------|--------|--------| diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index f3e52618ff6..065a597ae8b 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -2132,7 +2132,7 @@ Set `NEMOCLAW_HERMES_DASHBOARD_TUI=1` only when you want Hermes' optional in-bro ### Onboarding Configuration -These variables let you tune onboarding without editing the Dockerfile or passing repeated flags. +The following variables let you tune onboarding without editing the Dockerfile or passing repeated flags. Set them before running `$$nemoclaw onboard`. | Variable | Format | Effect | @@ -2291,7 +2291,8 @@ The run exits with an actionable diagnostic instead. ### Onboarding Behavior Flags -These flags toggle optional behaviors during onboarding; set them before running `$$nemoclaw onboard`. +The following flags toggle optional behaviors during onboarding. +Set them before running `$$nemoclaw onboard`. | Variable | Format | Effect | |----------|--------|--------| @@ -2358,7 +2359,7 @@ For a remote collector, create a custom preset for the collector host and port i ### Probe Timeouts -These tune how long internal probes wait before giving up. +The following variables tune how long internal probes wait before giving up. Defaults are sized for typical hardware; override only if you see false-positive timeouts. | Variable | Default | Effect | @@ -2389,7 +2390,7 @@ The readiness wait deletes the orphaned sandbox first so the next `$$nemoclaw on ### Lifecycle Behavior Flags -These flags change defaults for commands that manage existing sandboxes. +The following flags change defaults for commands that manage existing sandboxes. | Variable | Format | Effect | |----------|--------|--------| @@ -2401,7 +2402,7 @@ These flags change defaults for commands that manage existing sandboxes. ### Remote Deployment -These variables seed defaults for `$$nemoclaw deploy` and `$$nemoclaw onboard --remote`, which provision a sandbox on a Brev instance. +The following variables seed defaults for `$$nemoclaw deploy` and `$$nemoclaw onboard --remote`, which provision a sandbox on a Brev instance. Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu). diff --git a/docs/reference/enterprise-readiness.mdx b/docs/reference/enterprise-readiness.mdx index c2ccf9e0286..28d01153cd4 100644 --- a/docs/reference/enterprise-readiness.mdx +++ b/docs/reference/enterprise-readiness.mdx @@ -11,12 +11,13 @@ content: --- import { AgentOnly } from "../_components/AgentGuide"; -This page gives field teams and enterprise evaluators a single reference for what NemoClaw supports today, what an operator must handle manually, what the OpenShell platform or the inference provider owns, and what is roadmap-only. -Use it to answer enterprise readiness and support-boundary questions consistently instead of inferring an answer from individual bug fixes. +This page helps field teams and enterprise evaluators distinguish what NemoClaw supports today, what an operator must handle manually, what the OpenShell platform or inference provider owns, and what remains roadmap-only. +Use it to answer enterprise readiness and support-boundary questions consistently instead of inferring answers from individual bug fixes. NemoClaw is an open-source reference stack for running sandboxed agents more safely inside OpenShell. It is in active development, and interfaces can change between releases. -NemoClaw is not a hardened, multi-tenant enterprise control plane, and several admin and control-plane expectations are platform-owned or roadmap-only. +NemoClaw is not a hardened, multi-tenant enterprise control plane. +Several admin and control-plane expectations are platform-owned or roadmap-only. This page states where each capability stands so evaluators do not treat roadmap items as current commitments. @@ -44,8 +45,8 @@ For validated platform, inference, and launch claims, pair it with the launch cl ## Support Boundaries -NemoClaw orchestrates several components that it does not all own. -Knowing who enforces each boundary prevents misattributing a limitation to NemoClaw when the owner is OpenShell, the agent runtime, or the provider. +NemoClaw orchestrates several components with different owners. +Knowing who enforces each boundary prevents misattributing a limitation to NemoClaw when OpenShell, the agent runtime, or the provider owns it. | Component | Owner | Responsibility | |---|---|---| @@ -61,7 +62,7 @@ For the architecture behind these boundaries, refer to [How It Works](../about/h ## Enterprise Readiness by Capability Area The following matrix answers the most common enterprise evaluation questions. -Each row links to the deeper documentation and, where a concrete fix is in progress, to the tracked issue. +Each row links to deeper documentation and, when a concrete fix is in progress, the tracked issue. | Capability area | Status | Notes, workaround, and tracked work | |---|---|---| @@ -109,7 +110,7 @@ The following table classifies each admin and control-plane expectation by curre ## Known Limitations and Workarounds -These limitations are most likely to surface during an enterprise evaluation. +The following limitations are most likely to surface during an enterprise evaluation. Each one includes the current workaround or next step. | Limitation | Impact | Workaround or next step | diff --git a/docs/reference/network-policies.mdx b/docs/reference/network-policies.mdx index 4fb8c04be42..85ef0ad10ca 100644 --- a/docs/reference/network-policies.mdx +++ b/docs/reference/network-policies.mdx @@ -11,7 +11,7 @@ content: --- NemoClaw runs with a deny-by-default network policy. The sandbox can only reach endpoints that are explicitly allowed. -Any request to an unlisted destination is intercepted by OpenShell, and the operator is prompted to approve or deny it in real time through the TUI. +OpenShell intercepts any request to an unlisted destination and prompts the operator to approve or deny it in real time through the TUI. ## Baseline Policy @@ -95,12 +95,13 @@ Interactive onboarding ignores an invalid environment value and shows the normal ### Inference -The baseline policy allows only the `local` inference route. External inference -providers are reached through the OpenShell gateway, not by direct sandbox egress. +The baseline policy allows only the `local` inference route. +External inference providers are reached through the OpenShell gateway, not by direct sandbox egress. ## Operator Approval Flow -When the agent attempts to reach an endpoint not listed in the policy, OpenShell intercepts the request and presents it in the TUI for operator review: +When the agent attempts to reach an endpoint not listed in the policy, OpenShell intercepts the request and presents it in the TUI for operator review. +The flow has these steps: 1. The agent makes a network request to an unlisted host. 2. OpenShell blocks the connection and logs the attempt. diff --git a/docs/reference/platform-support.mdx b/docs/reference/platform-support.mdx index b74973e868b..e0c337a4f77 100644 --- a/docs/reference/platform-support.mdx +++ b/docs/reference/platform-support.mdx @@ -9,12 +9,13 @@ keywords: ["nemoclaw platform support", "nemoclaw launch claims", "nemoclaw supp content: type: "reference" --- -This page is the canonical reference for what NemoClaw supports today. Any documentation, demo, blog post, sales conversation, or support reply that describes NemoClaw capability should agree with the entries below. +This page is the canonical reference for what NemoClaw supports today. +Any documentation, demo, blog post, sales conversation, or support reply that describes a NemoClaw capability should match the entries below. The tables on this page are generated from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json). -Update the JSON; the tables and the partial views on other pages stay in sync with `scripts/generate-platform-docs.py`. +Update the JSON so the tables and partial views on other pages stay in sync with `scripts/generate-platform-docs.py`. -## Status vocabulary +## Status Vocabulary {/* status-vocabulary:begin */} | Status | Meaning | @@ -27,7 +28,7 @@ Update the JSON; the tables and the partial views on other pages stay in sync wi | Hermes only | Available only when onboarding the Hermes agent. | {/* status-vocabulary:end */} -## Project status +## Project Status For version highlights, see [Release Notes](../about/release-notes). @@ -46,7 +47,7 @@ For version highlights, see [Release Notes](../about/release-notes). The engineering owner is the GitHub team auto-assigned to review changes to `ci/platform-matrix.json` through CODEOWNERS, and the same team signs off on launch-facing claim changes before they reach demos, blog posts, or sales material. -### Review process +### Review Process 1. A change to a status or note opens a PR that touches `ci/platform-matrix.json`. 2. CODEOWNERS auto-requests review from the engineering owner team. @@ -85,7 +86,7 @@ For the onboarding-time supported set without deferred rows, see [Prerequisites] | NVIDIA RTX (consumer and Pro workstation GPUs) | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Covers RTX consumer cards and RTX Pro workstation cards on Linux hosts that meet the generic-Linux-GPU requirements (NVIDIA Container Toolkit + CDI present). The provider menu emits managed vLLM behind `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` for this host class today; the end-to-end onboard path on this hardware is not yet validated in CI. | {/* platform-matrix-full:end */} -## Inference providers +## Inference Providers NemoClaw routes inference through the OpenShell gateway. Each row below is a provider the onboarding wizard can configure end-to-end. @@ -105,7 +106,7 @@ NemoClaw routes inference through the OpenShell gateway. Each row below is a pro | Local vLLM (managed install/start) | Tested with limitations | Local OpenAI-compatible | Appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. Host must have the NVIDIA Container Toolkit installed and a CDI spec present (`onboard` asserts CDI presence). NemoClaw pulls or starts the stable NGC vLLM container for each host profile. See `src/lib/inference/vllm.ts:55,177` for the pins. DGX Spark and DGX Station use `nvcr.io/nvidia/vllm:26.05.post1-py3`; generic Linux NVIDIA GPU hosts use `nvcr.io/nvidia/vllm:26.03.post1-py3`. Validated defaults are listed in `src/lib/inference/vllm-models.ts`: DGX Spark uses `nvidia/Qwen3.6-35B-A3B-NVFP4`, DGX Station uses `Qwen/Qwen3.6-27B-FP8`, and Linux NVIDIA GPU uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8`. Image pulls require NGC registry login (`docker login nvcr.io`); onboard prompts for the NGC API key when authentication is missing. | {/* provider-status-full:end */} -## Messaging integrations +## Messaging Integrations NemoClaw configures messaging channels during onboarding. The OpenShell gateway runs each channel as a supervised process; NemoClaw supplies onboarding, credential delivery, and policy presets for the sandbox egress rules. @@ -138,9 +139,10 @@ Each row below is a launch-facing capability claim that NemoClaw makes in docs, | Web search backend | Tested with limitations | Runtime-configurable web-search backend plumbed through the OpenShell gateway. Brave is the currently-implemented backend. See `src/lib/onboard/brave-provider-profile.ts` and `src/lib/onboard/web-search-flow.ts`. Users supply backend credentials during an onboard prompt. NemoClaw does not bundle a key. | {/* capability-status:end */} -## Deployment paths +## Deployment Paths -How NemoClaw can be brought up on a given host. Pick the row that matches the target environment. +Use this section to choose how to bring up NemoClaw on a host. +Pick the row that matches the target environment. {/* deployment-status:begin */} | Path | Status | Notes | @@ -150,9 +152,10 @@ How NemoClaw can be brought up on a given host. Pick the row that matches the ta | Brev web UI | Tested | Browser-driven launcher provisions a Brev-managed Linux VM with Docker, the OpenShell runtime, a NemoClaw sandbox running OpenClaw, inference routing, and the OpenClaw dashboard. | {/* deployment-status:end */} -## Out of scope and not supported +## Out of Scope and Not Supported -The items below come up in conversations but are explicitly out of scope. They are listed here so launch material, sales conversations, and support triage have a clear "we do not claim to do this" reference. +The items below come up in conversations but are explicitly out of scope. +They are listed here so launch material, sales conversations, and support triage have a clear "we do not claim to do this" reference. {/* out-of-scope:begin */} | Item | Status | Why | @@ -171,18 +174,18 @@ The items below come up in conversations but are explicitly out of scope. They a | Production SLA or guaranteed response times | Unsupported | NemoClaw is an early-preview alpha project. Maintainers respond on a best-effort basis. No SLA is offered. | {/* out-of-scope:end */} -## Known caveats and active blockers +## Known Caveats and Active Blockers - Sandbox bounding-set capability drop on hosts without `CAP_SETPCAP` is partially fixed. The agent process tree drops dangerous caps with `NEMOCLAW_REQUIRE_CAP_DROP=1` (see [#4707](https://github.com/NVIDIA/NemoClaw/pull/4707)). The `nemoclaw connect` shell still inherits the container's create-time bounding set on Colossus, Docker Desktop, and WSL hosts where `CAP_SETPCAP` is absent. The remaining fix is upstream in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452). See tracking [#3280](https://github.com/NVIDIA/NemoClaw/issues/3280). -## Using this matrix +## Using This Matrix - Docs and READMEs that reference any row above should link to this page instead of restating status. Partial tables, such as the prerequisites page, generate from the same JSON and stay in sync with `scripts/generate-platform-docs.py`. - Demos and launch material should cite the status verbatim. A "Tested with limitations" row is not a "Tested" row. - Customer support can use the matrix to triage incoming reports. A failure on a Tested row is a bug. A failure on a Deferred row is an unsupported configuration request. A failure on an Unsupported row is a feature request that needs separate triage. - Roadmap changes land in the JSON first, then propagate to this page on the next generator run. -## Updating the matrix +## Updating the Matrix 1. Edit [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json). 2. Run `python3 scripts/generate-platform-docs.py` to regenerate this page and the partial tables on prerequisites and inference-options. diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index a892e8803af..0e0d1c57561 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -11,13 +11,12 @@ content: --- {/* markdownlint-disable MD014 */} -# Troubleshooting - -This page covers common issues you may encounter when installing, onboarding, or running NemoClaw, along with their resolution steps. +This page covers common installation, onboarding, and runtime issues, along with resolution steps. -If your issue is not listed here, join the [NemoClaw Discord channel](https://discord.gg/XFpfPv9Uvx) to ask questions and get help from the community. You can also [file an issue on GitHub](https://github.com/NVIDIA/NemoClaw/issues/new). +If your issue is not listed here, join the [NemoClaw Discord channel](https://discord.gg/XFpfPv9Uvx) to ask questions and get help from the community. +You can also [file an issue on GitHub](https://github.com/NVIDIA/NemoClaw/issues/new). ## Installation @@ -61,7 +60,9 @@ Then re-run the installer. ### Image push fails with out-of-memory errors -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, which buffers decompressed layers in memory. On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. +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, which 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. @@ -154,7 +155,10 @@ If the Jetson setup step fails, verify that you have `sudo` access and that Dock For JetPack 6 (L4T 36.x), the setup switches iptables to legacy mode and adjusts the Docker daemon configuration. For JetPack 7 (L4T 38.x / Thor), only bridge netfilter and sysctl settings are applied. -For JetPack 7 (L4T 39.x), bridge netfilter is loaded only when the host is missing it. Some R39 images already ship with `br_netfilter` configured and are left untouched. On affected R39 hosts, the installer prints `loading br_netfilter (required by k3s inside the OpenShell gateway)`. Without this fix, sandbox pods fail DNS resolution against the in-cluster service and the onboard `Setting up OpenClaw inside sandbox` step times out. +For JetPack 7 (L4T 39.x), bridge netfilter is loaded only when the host is missing it. +Some R39 images already ship with `br_netfilter` configured and are left untouched. +On affected R39 hosts, the installer prints `loading br_netfilter (required by k3s inside the OpenShell gateway)`. +Without this fix, sandbox pods fail DNS resolution against the in-cluster service and the onboard `Setting up OpenClaw inside sandbox` step times out. If the L4T version is not recognized, the setup step is skipped and the installer continues normally. @@ -235,9 +239,7 @@ Or set the port directly: NEMOCLAW_DASHBOARD_PORT=19000 $$nemoclaw onboard ``` -For an OpenShell gateway port conflict, set `NEMOCLAW_GATEWAY_PORT` to a free -non-privileged port that does not overlap NemoClaw's dashboard, vLLM, Ollama, -or Ollama proxy ports: +For an OpenShell gateway port conflict, set `NEMOCLAW_GATEWAY_PORT` to a free non-privileged port that does not overlap NemoClaw's dashboard, vLLM, Ollama, or Ollama proxy ports: ```bash NEMOCLAW_GATEWAY_PORT=8990 $$nemoclaw onboard @@ -249,8 +251,7 @@ Remote/headless hosts can bind the OpenShell gateway to all IPv4 interfaces: NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0 NEMOCLAW_GATEWAY_PORT=8990 $$nemoclaw onboard ``` -Use `NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0` only when other hosts on the -network should be able to reach the gateway. +Use `NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0` only when other hosts on the network should be able to reach the gateway. See [Environment Variables](commands#environment-variables) for the full list of port overrides. @@ -313,7 +314,7 @@ failed to mount overlay: ... err: invalid argument ``` This is a Docker default-driver change, not a NemoClaw or OpenShell regression. -The same hardware running Docker 25 or earlier — or any Docker version with the containerd image store disabled — uses the legacy `overlay2` driver and is unaffected. +The same hardware uses the legacy `overlay2` driver and is unaffected when it runs Docker 25 or earlier, or any Docker version with the containerd image store disabled. NemoClaw detects the Docker 26+ containerd-snapshotter overlayfs configuration during onboarding and transparently builds a small drop-in replacement for the cluster image on the local Docker engine. The patched image installs `fuse-overlayfs` and selects it as the k3s snapshotter, bypassing the kernel-level nested-overlay limitation. @@ -325,9 +326,9 @@ Hosts without the conflict (`Driver: overlay2` in `docker info`, macOS Docker De Override knobs: -- `NEMOCLAW_DISABLE_OVERLAY_FIX=1` — skip the auto-fix and run against the unmodified upstream cluster image. +- `NEMOCLAW_DISABLE_OVERLAY_FIX=1`: skip the auto-fix and run against the unmodified upstream cluster image. Useful for diagnosis or when you have already applied the manual workaround below. -- `NEMOCLAW_OVERLAY_SNAPSHOTTER=native` — build the patched image with k3s's `native` snapshotter instead of `fuse-overlayfs`. +- `NEMOCLAW_OVERLAY_SNAPSHOTTER=native`: build the patched image with k3s's `native` snapshotter instead of `fuse-overlayfs`. The `native` snapshotter copies image layers instead of overlaying them, so it uses more disk but does not depend on FUSE. Default is `fuse-overlayfs`. @@ -341,7 +342,8 @@ If you prefer to disable the new Docker storage driver instead of running the pa ``` Then restart Docker (`sudo systemctl restart docker`) and re-run `$$nemoclaw onboard`. -This restores the legacy `overlay2` driver host-wide, which kills any other running containers — prefer the auto-fix unless you need the change for unrelated reasons. +This restores the legacy `overlay2` driver host-wide, which kills any other running containers. +Prefer the auto-fix unless you need the change for unrelated reasons. Switching storage drivers also rebuilds the entire local image graph: previously-pulled images become unusable and Docker re-pulls them on first reference, so expect a cold cache and additional disk usage right after the restart. ### OpenShell version above maximum @@ -403,7 +405,8 @@ NemoClaw prevents and self-heals this: - The generated sandbox config pins `gateway.reload.mode` to `hot`, so configuration changes never make the gateway restart itself out from under the sandbox supervisor. - A serving watchdog inside the sandbox kills a gateway that stops listening after it has served, and the supervisor relaunches it (look for `[gateway-watchdog]` lines in `$$nemoclaw logs`). -Because of the `hot` pin, restart-class configuration changes made inside the sandbox — for example `openclaw plugins install` — log `config reload requires gateway restart; hot mode ignoring` and do not take effect until the gateway restarts. +Because of the `hot` pin, restart-class configuration changes made inside the sandbox log `config reload requires gateway restart; hot mode ignoring` and do not take effect until the gateway restarts. +For example, `openclaw plugins install` logs that message until the gateway restarts. Apply them with a supervised restart: ```bash @@ -478,15 +481,12 @@ To silence the warning when the host is intentionally small, set `NEMOCLAW_IGNOR ### Re-onboard fails because port 18789 is held by SSH -After destroying a sandbox and gateway, the SSH port-forward process for the -dashboard can be left running. +After destroying a sandbox and gateway, the SSH port-forward process for the dashboard can be left running. Re-running onboard then fails preflight with `Port 18789 is not available. Blocked by: ssh`. -Current NemoClaw detects this case and kills the orphaned SSH process -automatically before retrying the port check. -If you see the error on an older release, identify the SSH process and -terminate it manually: +Current NemoClaw detects this case and kills the orphaned SSH process automatically before retrying the port check. +If you see the error on an older release, identify the SSH process and terminate it manually: ```bash sudo lsof -i :18789 @@ -497,17 +497,11 @@ Then re-run `$$nemoclaw onboard`. ### Updated messaging token is not picked up -Re-running `$$nemoclaw onboard --non-interactive` with a new -`TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, or `SLACK_BOT_TOKEN` previously -reported success while the sandbox kept polling with the old credential. -Current NemoClaw stores SHA-256 hashes of messaging credentials in the -sandbox registry at creation time and detects when a token has changed. -When rotation is detected, NemoClaw automatically backs up workspace state, -deletes the sandbox, recreates it with the new credential, and restores the -backup. +Re-running `$$nemoclaw onboard --non-interactive` with a new `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, or `SLACK_BOT_TOKEN` previously reported success while the sandbox kept polling with the old credential. +Current NemoClaw stores SHA-256 hashes of messaging credentials in the sandbox registry at creation time and detects when a token has changed. +When rotation is detected, NemoClaw automatically backs up workspace state, deletes the sandbox, recreates it with the new credential, and restores the backup. -If you suspect a sandbox is still using a stale token, re-run onboarding so -the credential check runs: +If you suspect a sandbox is still using a stale token, re-run onboarding so the credential check runs: ```bash $$nemoclaw onboard --non-interactive @@ -755,7 +749,9 @@ Onboarding ends with: The orphaned sandbox has been removed — you can safely retry. ``` -This is a separate budget from `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` — it covers the readiness wait that follows sandbox creation (in-sandbox boot, OpenClaw start, policy load), not the inference probe. +This is a separate budget from `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT`. +It covers the readiness wait that follows sandbox creation, including in-sandbox boot, OpenClaw start, and policy load. +It does not cover the inference probe. The 180-second default fits typical workstations but can be exceeded when: - The host is building or uploading the sandbox image for the first time (cold caches, slow link). @@ -801,9 +797,8 @@ Responses API, unset it before re-running onboard. When you enable Telegram messaging with an OpenAI-compatible endpoint, onboarding also checks `inference.local` from inside the sandbox. If that smoke check fails, fix the compatible-endpoint base URL, credentials, model, or network route before testing the Telegram bot again. -Do not rely on `NEMOCLAW_INFERENCE_API_OVERRIDE` alone — it patches the config -at container startup but does not update the Dockerfile ARG baked into the -image. +Do not rely on `NEMOCLAW_INFERENCE_API_OVERRIDE` alone. +It patches the config at container startup but does not update the Dockerfile ARG baked into the image. A fresh `$$nemoclaw onboard` is the reliable fix. ### `NEMOCLAW_DISABLE_DEVICE_AUTH=1` does not change an existing sandbox @@ -1167,22 +1162,18 @@ Refer to [Customize the Network Policy](../network-policy/customize-network-poli ### Dashboard not reachable after setting a custom port -If you ran `$$nemoclaw onboard` with a custom dashboard port and onboarding completed -but the dashboard URL is unreachable (browser shows connection refused or the page fails -to load), the sandbox was most likely created with an older NemoClaw version that did not -pass the dashboard port into the sandbox at startup. The gateway inside the sandbox -continued listening on the default port 18789 while the SSH tunnel forwarded the custom -port — leaving nothing at the other end of the tunnel. +If you ran `$$nemoclaw onboard` with a custom dashboard port and onboarding completed but the dashboard URL is unreachable, the sandbox was most likely created with an older NemoClaw version that did not pass the dashboard port into the sandbox at startup. +The browser may show connection refused or fail to load the page. +The gateway inside the sandbox continued listening on the default port 18789 while the SSH tunnel forwarded the custom port, leaving nothing at the other end of the tunnel. -Re-run onboarding on the current NemoClaw release with the desired port. Current versions -derive the dashboard port from `CHAT_UI_URL` automatically and inject it into the sandbox: +Re-run onboarding on the current NemoClaw release with the desired port. +Current versions derive the dashboard port from `CHAT_UI_URL` automatically and inject it into the sandbox: ```bash CHAT_UI_URL=http://127.0.0.1:19000 $$nemoclaw onboard ``` -If you need to run multiple sandboxes at different ports at the same time, see -[Running multiple sandboxes simultaneously](#running-multiple-sandboxes-simultaneously). +If you need to run multiple sandboxes at different ports at the same time, see [Running multiple sandboxes simultaneously](#running-multiple-sandboxes-simultaneously). ### Control UI config endpoint returns 404 or non-JSON @@ -1413,7 +1404,8 @@ openshell sandbox delete Fix the NVIDIA Container Toolkit or CDI configuration reported in the diagnostics, clean up the failed sandbox, then rerun onboarding. If you do not need GPU access inside the sandbox, rerun with `--no-sandbox-gpu`. Set `NEMOCLAW_DOCKER_GPU_PATCH=0` only when you need to bypass this compatibility path during troubleshooting. -On Docker Desktop WSL the patch is required for GPU passthrough — `NEMOCLAW_DOCKER_GPU_PATCH=0` is ignored on that runtime, and onboarding logs a warning when it is set there. +On Docker Desktop WSL, the patch is required for GPU passthrough. +`NEMOCLAW_DOCKER_GPU_PATCH=0` is ignored on that runtime, and onboarding logs a warning when it is set there. To skip GPU passthrough entirely on Docker Desktop WSL, rerun with `--no-gpu` or set `NEMOCLAW_SANDBOX_GPU=0`. If sandbox creation fails with `CDI device injection failed: unresolvable CDI devices nvidia.com/gpu=all`, the OpenShell gateway tried `docker create --device nvidia.com/gpu=all` and Docker could not resolve the CDI spec. diff --git a/docs/resources/agent-skills.mdx b/docs/resources/agent-skills.mdx index afc7f6a8cb8..4a1ec7f9431 100644 --- a/docs/resources/agent-skills.mdx +++ b/docs/resources/agent-skills.mdx @@ -11,10 +11,10 @@ content: --- import { StarterPromptButton } from "../_components/StarterPromptButton"; -NemoClaw publishes an MCP docs server and clean Markdown versions of its Fern documentation for AI coding agents. -Your agent can search or fetch the same canonical pages that appear on the docs site, then apply that guidance to your local setup. +NemoClaw publishes an MCP docs server and Markdown versions of its Fern documentation for AI coding agents. +Your agent can search or fetch the same canonical pages that appear on the docs site and apply that guidance to your local setup. -Use this page when you want your agent to help with installation, inference configuration, network policy management, monitoring, deployment, security, workspace management, or command reference lookup. +Use this page when you want your agent to help with installation, inference configuration, network policies, monitoring, deployment, security, workspace management, or command reference lookup. ## Give Your Agent the Starter Prompt @@ -25,7 +25,7 @@ The prompt tells the agent to use the Markdown docs, ask one question at a time, ## Configure the Docs MCP Server -If your coding agent supports MCP, configure the NemoClaw docs server before you ask installation or troubleshooting questions. +If your coding agent supports MCP, configure the NemoClaw docs server before you ask installation, configuration, or troubleshooting questions. The server URL is `https://docs.nvidia.com/nemoclaw/_mcp/server`. It exposes a read-only `searchDocs` tool that searches the NemoClaw documentation and returns source URLs. @@ -40,8 +40,8 @@ For other MCP clients, configure a streamable HTTP MCP server at that URL. ## Optional Docs-Routing Skill -If your coding agent supports local project skills, you can fetch the single user skill that encodes the same routing rules. -This skill is small because it points back to the Markdown docs instead of copying the docs into the repository. +If your coding agent supports local project skills, fetch the user skill that encodes the same routing rules. +The skill stays small because it points back to the Markdown docs instead of copying page content into the repository. Fetch only the docs-routing skill and root instructions without downloading the full source tree: @@ -53,4 +53,4 @@ git checkout ``` Open the `NemoClaw` directory in your AI coding assistant. -The assistant discovers `nemoclaw-user-guide` and uses it to fetch the relevant Markdown documentation. +The assistant discovers `nemoclaw-user-guide` and uses it to fetch relevant Markdown documentation. diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx index 64f37ebc4ef..59842bcc638 100644 --- a/docs/security/best-practices.mdx +++ b/docs/security/best-practices.mdx @@ -1,7 +1,7 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "NemoClaw Security Best Practices: Controls, Risks, and Posture Profiles" +title: "NemoClaw Security Controls, Risks, and Posture Profiles" sidebar-title: "Security Best Practices" description: "A risk framework for every configurable security control in NemoClaw: defaults, what you can change, and what happens if you do." description-agent: "Presents a risk framework for every configurable security control in NemoClaw. Use when evaluating security posture, reviewing sandbox security defaults, or assessing control trade-offs." @@ -92,7 +92,7 @@ flowchart TB ## Network Controls -NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets operators approve or deny requests in real time. +NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets you approve or deny requests in real time. Network policy allowlists do not disable OpenShell's SSRF guard; see [Customize the Network Policy](/network-policy/customize-network-policy) for the interaction between egress rules and internal-address blocking. {/* OpenShell provides additional network enforcement mechanisms not covered here, including network namespace isolation, SSRF protection, TLS auto-detection and termination, and audit-vs-enforce modes. @@ -111,7 +111,7 @@ The sandbox blocks all outbound connections unless you explicitly list the endpo ### Binary-Scoped Endpoint Rules -Each network policy entry restricts which executables can reach the endpoint using the `binaries` field. +Each network policy entry uses the `binaries` field to restrict which executables can reach the endpoint. OpenShell identifies the calling binary by reading `/proc//exe` (the kernel-trusted executable path, not `argv[0]`), walking the process tree for ancestor binaries, and computing a SHA256 hash of each binary on first use. If someone replaces a binary while the sandbox runs, the hash mismatch immediately denies the request. @@ -120,7 +120,7 @@ If someone replaces a binary while the sandbox runs, the hash mismatch immediate |---|---| | Default | Each endpoint restricts access to specific binaries. For example, the `github` preset restricts access so only `/usr/bin/git` can reach `github.com`. Binary paths support glob patterns (`*` matches one path component, `**` matches recursively). | | What you can change | Add binaries to an endpoint entry, or omit the `binaries` field to allow any executable. | -| Risk if relaxed | Removing binary restrictions lets any process in the sandbox reach the endpoint. An agent could use `curl`, `wget`, or a Python script to exfiltrate data to an allowed host, bypassing the intended usage pattern. | +| Risk if relaxed | Removing binary restrictions lets any process in the sandbox reach the endpoint. An agent can use `curl`, `wget`, or a Python script to exfiltrate data to an allowed host, bypassing the intended usage pattern. | | Recommendation | Always scope endpoints to the binaries that need them. If the agent needs a host from a new binary, add that binary explicitly rather than removing the restriction. | ### Path-Scoped HTTP Rules @@ -153,7 +153,7 @@ When the agent reaches an unlisted endpoint, OpenShell blocks the request and pr | Aspect | Detail | |---|---| | Default | Enabled. The gateway blocks all unlisted endpoints and requires approval. | -| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox through onboarding, the policy resets to the baseline defined in the blueprint. | +| What you can change | OpenShell merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. When you destroy and recreate the sandbox through onboarding, the policy resets to the baseline defined in the blueprint. | | Risk if relaxed | Approving an endpoint permanently widens the running sandbox's policy. If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. | | Recommendation | Review each blocked request before approving. If you find yourself approving the same endpoint repeatedly, add it to the baseline policy with appropriate binary and path restrictions. To reset approved endpoints, destroy and recreate the sandbox. | @@ -177,7 +177,8 @@ NemoClaw ships preset policy files in `nemoclaw-blueprint/policies/presets/` for | `slack` | Slack API, Socket Mode, webhooks. | WebSocket uses `access: full`. Agent can post to any channel the bot token has access to. | | `telegram` | Telegram Bot API. | Agent can send messages to any chat the bot token has access to. | -**Recommendation:** Apply presets only when the agent's task requires the integration. Review the preset's YAML file before applying to understand the endpoints, methods, and binary restrictions it adds. +Apply presets only when the agent's task requires the integration. +Review the preset's YAML file before applying to understand the endpoints, methods, and binary restrictions it adds. ## Filesystem Controls @@ -208,27 +209,36 @@ In root mode, the gateway process still runs as the separate `gateway` user, but Writable agent state such as plugins, skills, hooks, and workspace metadata lives directly under `/sandbox/.openclaw`. By default, this directory starts writable so the agent can manage its own config, install skills, and write to standard home-directory paths natively. -For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so the sandbox user cannot change config and high-risk state entry points. +For sensitive workloads, use a reviewed host-side immutability workflow after initial setup so the sandbox user cannot change config or high-risk state entry points. The immutability workflow locks high-risk state directories (`skills`, `hooks`, `cron`, `agents`, `extensions`, `plugins`, `workspace`, `memory`, `devices`, `canvas`, `telegram`, `wechat`, `whatsapp`, `platforms`, `weixin`, `profiles`, `skins`) to `root:sandbox` with `chmod -R go-w`. The OpenClaw gateway (a member of the `sandbox` group) keeps read access to plugin and agent code; the sandbox user can no longer write them. The same workflow also locks the secret-bearing directories (`credentials`, `identity`, `pairing`) to `root:root 700` with `chmod -R go-rwX`. Neither the sandbox user nor the gateway can read those secrets while the lock is active. -Restoring the mutable-default posture returns both groups to `sandbox:sandbox 2770`. -The list is the union of state directories declared by every shipped agent manifest; the lock helper silently skips dirs that aren't present in a given agent's config tree. +Restoring the mutable-default posture returns those directories to `sandbox:sandbox 2770`. +The list is the union of state directories declared by every shipped agent manifest. +The lock helper silently skips dirs that are not present in a given agent's config tree. Two exemption kinds keep runtime data writable. -The lock inventory omits top-level Hermes runtime dirs (`sessions/`, `memories/`, `logs/`, `cache/`, `plans/`) and the image-build-regenerated `openclaw-weixin/`; the lock helper never touches those paths. +The lock inventory omits top-level Hermes runtime dirs (`sessions/`, `memories/`, `logs/`, `cache/`, `plans/`) and the image-build-regenerated `openclaw-weixin/`. +The lock helper never touches those paths. Inside a locked tree, the helper restores `agents//sessions/` to `sandbox:sandbox 2770` after the surrounding `agents/` lock so the OpenClaw TUI can create and write session metadata under an otherwise root-owned parent. If any high-risk state-dir root is a symlink when the lock runs, the lock helper refuses to proceed and reports "Config not locked: state dir root is a symlink" instead of following the link with privileged `chown -R` / `chmod -R`. -- **DAC permissions (default).** The sandbox user owns `/sandbox/.openclaw` with mode `2770` (setgid `sandbox:sandbox`) and `openclaw.json` with mode `660`, so the agent and its group can read and write config directly. A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked. -- **Config integrity hash.** The image includes a SHA256 hash of `openclaw.json`. In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match. +- **DAC permissions (default).** + The sandbox user owns `/sandbox/.openclaw` with mode `2770` (setgid `sandbox:sandbox`) and `openclaw.json` with mode `660`, so the agent and its group can read and write config directly. + A reviewed host-side immutability workflow should compare the intended ownership and mode with the live sandbox filesystem before treating the config tree as locked. +- **Config integrity hash.** + The image includes a SHA256 hash of `openclaw.json`. + In the default mutable state, `.config-hash` is sandbox-owned and is not a tamper-proof trust anchor, so startup does not fail closed on that hash. + When the hash is root-owned and read-only, startup enforces it and refuses to start if the hash does not match. - **Content integrity seal.** A clean immutable config lock can capture a SHA-256 seal of `openclaw.json` and other locked files into host-side state. Verification recomputes hashes inside the sandbox and surfaces drift on mismatch, so a host-root tamper that flips permissions back to `444 root:root` after rewriting the file is still flagged. Sandboxes locked before the seal landed have no recorded hash; permission-only verification cannot prove their bytes match the image original, so the seal is **not** a retroactive proof of integrity for legacy state. The same limitation applies when the locked file set grew after the existing seal was captured. Rebuild the sandbox for a known-good baseline before trusting a new seal. -- **Gateway token environment.** The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture. +- **Gateway token environment.** + The gateway exports `OPENCLAW_GATEWAY_TOKEN` and writes it to `/tmp/nemoclaw-proxy-env.sh` for interactive sandbox sessions. + Keep this in mind when deciding whether a workload should run with mutable config or an immutable config posture. | Aspect | Detail | |---|---| @@ -294,16 +304,21 @@ When the entrypoint switches from root to the `sandbox` and `gateway` users, it The initial entrypoint drop removes `cap_sys_admin`, `cap_sys_ptrace`, `cap_net_raw`, `cap_dac_override`, `cap_sys_chroot`, `cap_fsetid`, `cap_setfcap`, `cap_mknod`, `cap_audit_write`, and `cap_net_bind_service`. During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setgid`, `cap_fowner`, `cap_chown`, and `cap_kill`. -This behavior is best effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set. +This 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. To make the drop fail-closed instead of best-effort, set `NEMOCLAW_REQUIRE_CAP_DROP=1` in the entrypoint environment. -The agent then refuses to start unless the agent process tree's bounding set is verified free of the dangerous capabilities, so it will not boot on a host whose bounding set still holds them — typically one that cannot perform the drop (no `CAP_SETPCAP`, or `capsh` missing) and was not given a clean bounding set by the container runtime. -This is opt-in because such hosts are common (many cloud VMs, Docker Desktop, WSL); leaving it unset preserves the best-effort default. -The check covers the agent process tree only — a `$$nemoclaw connect` shell is spawned by the container runtime outside that tree and is not affected (tracked in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452)). +The agent then refuses to start unless it verifies that the agent process tree's bounding set is free of dangerous capabilities. +It does not boot on a host whose bounding set still holds them, typically one that cannot perform the drop because `CAP_SETPCAP` or `capsh` is missing and the container runtime did not provide a clean bounding set. +This is opt-in because such hosts are common, including many cloud VMs, Docker Desktop, and WSL. +Leaving it unset preserves the best-effort default. +The check covers the agent process tree only. +The container runtime spawns a `$$nemoclaw connect` shell outside that tree, so the check does not affect it (tracked in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452)). -For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose. Refer to [Sandbox Hardening](../deployment/sandbox-hardening). +For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose. +Refer to [Sandbox Hardening](../deployment/sandbox-hardening). | Aspect | Detail | @@ -339,7 +354,8 @@ The `no-new-privileges` flag prevents processes from gaining additional privileg A process limit caps the number of processes the sandbox user can spawn. The entrypoint sets both soft and hard limits using `ulimit -u 512`. -This behavior is best effort: if the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit. +This behavior is best effort. +If the container runtime restricts `ulimit` modification, the entrypoint logs a security warning and continues without the limit. | Aspect | Detail | |---|---| @@ -350,17 +366,16 @@ This behavior is best effort: if the container runtime restricts `ulimit` modifi ### Open File Descriptor Limit -An open file descriptor limit caps the number of files, sockets, and pipes the -sandbox user can hold open at once. The entrypoint sets both soft and hard -limits using `ulimit -n 65536`. This is best-effort: if the container runtime -restricts `ulimit` modification, the entrypoint logs a security warning and -continues without the limit. +An open file descriptor limit caps the number of files, sockets, and pipes the sandbox user can hold open at once. +The entrypoint sets both soft and hard limits using `ulimit -n 65536`. +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 | |---|---| | Default | 65536 open files, soft and hard (`ulimit -n 65536`), best-effort. | | What you can change | Increase or decrease the limit with `--ulimit nofile=N:N` in `docker run` or the `ulimits` section in Compose. The runtime-level ulimit takes precedence over the entrypoint's setting. | -| Risk if relaxed | Without this cap the sandbox inherits the Docker daemon default (`nofile` ~1048576). A runaway or hostile process can then open file descriptors until it exhausts them — a denial-of-service that can starve the gateway, the agent, or the host of file handles. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nofile limit`), the container runs without a file-descriptor cap. Ref [#4527](https://github.com/NVIDIA/NemoClaw/issues/4527). | +| Risk if relaxed | Without this cap, the sandbox inherits the Docker daemon default (`nofile` ~1048576). A runaway or hostile process can then open file descriptors until it exhausts them, causing a denial of service that can starve the gateway, the agent, or the host of file handles. If the entrypoint cannot set the limit (logs `[SECURITY] Could not set soft/hard nofile limit`), the container runs without a file-descriptor cap. Ref [#4527](https://github.com/NVIDIA/NemoClaw/issues/4527). | | Recommendation | Keep the default at 65536. If the agent legitimately keeps many connections or files open, raise it deliberately and monitor host file-descriptor usage. If the entrypoint logs a warning about ulimit restrictions, set the limit through the container runtime instead. | ### Non-Root User @@ -499,7 +514,7 @@ The CLI automatically redacts secret patterns (API keys, bearer tokens, provider The NemoClaw plugin blocks the agent from writing likely secrets (API keys, tokens, private keys) into persistent memory files. -The scanner intercepts Write, Edit, and similar tool calls targeting memory and workspace paths before they reach disk. +The scanner intercepts `Write`, `Edit`, and similar tool calls targeting memory and workspace paths before they reach disk. | Aspect | Detail | |---|---| @@ -546,7 +561,9 @@ Different inference providers have different trust and cost profiles. | Local Ollama | Self-hosted. No data leaves the machine. | No per-token cost. GPU/CPU resource cost. | Data stays local. | | Custom compatible endpoint | Varies. Depends on the proxy or gateway. | Varies. | Depends on the endpoint operator. | -**Recommendation:** For sensitive workloads, use local Ollama to keep data on-premise. For general use, NVIDIA Endpoints provide a good balance of capability and trust. Review the data policies of any cloud provider you use. +For sensitive workloads, use local Ollama to keep data on-premise. +For general use, NVIDIA Endpoints provide a balance of capability and trust. +Review the data policies of any cloud provider you use. ### Experimental Providers @@ -571,7 +588,7 @@ They provide guidance on which controls to keep tight or relax. Use for always-on assistants with minimal external access. -- Keep all defaults. Do not add presets. +- Keep all defaults and do not add presets. - Use operator approval for any endpoint the agent requests. - Use NVIDIA Endpoints or local Ollama for inference. - Monitor the TUI for unexpected network requests. @@ -592,7 +609,7 @@ Use when the agent talks to internal APIs or third-party services during testing - Add custom endpoint entries with tight path and method restrictions. - Use `protocol: rest` for all HTTP APIs to maintain inspection. - Use operator approval for unknown endpoints during test runs. -- Review and clean up the baseline policy after testing. Remove endpoints that are no longer needed. +- Review and clean up the baseline policy after testing by removing endpoints that are no longer needed. ## Common Mistakes diff --git a/docs/security/credential-storage.mdx b/docs/security/credential-storage.mdx index 9970c998f60..200ac46f9a0 100644 --- a/docs/security/credential-storage.mdx +++ b/docs/security/credential-storage.mdx @@ -14,14 +14,15 @@ import { AgentOnly } from "../_components/AgentGuide"; NemoClaw does not persist provider credentials to host disk. The OpenShell gateway is the only system of record for stored credentials. -When you provide a provider credential, either interactively during `$$nemoclaw onboard` or through an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. +When you provide a provider credential, either interactively during `$$nemoclaw onboard` or with an environment variable, NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret. The sandbox-side OpenClaw gateway token is generated at container startup and is not rotated through provider credential commands. -Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. +NemoClaw manages Hermes API credentials and provider credentials through the same OpenShell provider boundary. +NemoClaw recreates generated Hermes runtime files during rebuilds. Those files should contain resolver placeholders, not live provider credentials. For managed tools and messaging, NemoClaw keeps host-side auth in OpenShell providers or host brokers and writes placeholder values into `/sandbox/.hermes/config.yaml`, `/sandbox/.hermes/.env`, and process environment entries visible to the sandbox. Hermes startup rejects raw secret-shaped values in those sandbox-visible surfaces. @@ -30,20 +31,21 @@ Hermes startup rejects raw secret-shaped values in those sandbox-visible surface ## Where Credentials Live Provider credentials live in the OpenShell gateway store. -List what is registered with: +List registered provider names with: ```bash openshell provider list ``` -Or, equivalently, through NemoClaw: +Or use NemoClaw: ```bash $$nemoclaw credentials list ``` Both commands show the provider names registered with the gateway. -The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. +The CLI cannot read the values back. +OpenShell deliberately preserves this property. 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. @@ -51,16 +53,17 @@ That directory is created with mode `0700` and contains no credential material. ## Environment Variables Take Precedence When a NemoClaw command needs a credential value during a single run (for example to forward it to an `openshell provider` registration), it reads from `process.env` first. -This means you can: +Use this precedence to: -- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_INFERENCE_API_KEY=nvapi-... $$nemoclaw onboard` -- Use short-lived or rotated credentials in CI by exporting them once per pipeline run -- Avoid registering credentials in the gateway entirely if your environment supplies them +- Prefix any command with the credential to override the gateway-stored value: `NVIDIA_INFERENCE_API_KEY=nvapi-... $$nemoclaw onboard`. +- Use short-lived or rotated credentials in CI by exporting them once per pipeline run. +- Avoid registering credentials in the gateway entirely if your environment supplies them. When the host environment is empty, day-two operations such as `$$nemoclaw rebuild` and remote-provider updates can reuse the credential already registered with the OpenShell gateway. Export the credential only when you want to create, replace, or rotate the stored provider value. For rebuilds that use a non-local upstream provider, the matching OpenShell provider entry must still exist. -If the sandbox registry points at a provider that is missing from OpenShell, `$$nemoclaw rebuild` stops before backup or delete even when the matching credential environment variable is exported; rerun `$$nemoclaw onboard` or re-register the provider first. +If the sandbox registry points at a provider that is missing from OpenShell, `$$nemoclaw rebuild` stops before backup or delete even when you export the matching credential environment variable. +Rerun `$$nemoclaw onboard` or re-register the provider first. ## Deploy Reads from Environment Only @@ -75,15 +78,16 @@ NVIDIA_INFERENCE_API_KEY=nvapi-... \ ``` For remote vLLM or Hugging Face workflows that need gated model access, `$$nemoclaw deploy` also forwards `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` to the VM when either variable is present. -If a required credential is missing the deploy aborts before any remote work begins. +If a required credential is missing, deploy aborts before any remote work begins. ## GitHub Tokens NemoClaw never persists `GITHUB_TOKEN` itself. -When a private repo requires authentication NemoClaw runs `gh auth token`, which returns whatever the GitHub CLI has stored — without caring about the storage backend. +When a private repo requires authentication, NemoClaw runs `gh auth token`, which returns whatever the GitHub CLI has stored. +NemoClaw does not depend on the storage backend. 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`. +On hosts where no keychain is reachable, such as CI runners, headless launches, WSL without a session bus, or macOS contexts where Keychain access is blocked, `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. @@ -100,13 +104,13 @@ On first `$$nemoclaw onboard` after upgrading, NemoClaw automatically: 3. Re-registers each value with the OpenShell gateway through the normal onboarding path. 4. Securely overwrites and deletes `~/.nemoclaw/credentials.json` only after every staged value has been verified as migrated to the gateway. -You will see a one-line stderr notice the first time this happens. +You see a one-line stderr notice the first time this happens. Credential lookup paths such as rebuild also stage allowlisted legacy values so interrupted upgrades can keep working, but those staging-only paths do not delete the plaintext file because they cannot prove every legacy value was registered with the gateway. If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `$$nemoclaw onboard` to complete the verified gateway migration and cleanup. ## Rotate or Remove a Stored Credential -The simplest way to replace a stored value is to rerun onboarding with the new value in your environment: +To replace a stored value, rerun onboarding with the new value in your environment: ```bash NVIDIA_INFERENCE_API_KEY=nvapi-new-value $$nemoclaw onboard @@ -126,7 +130,8 @@ On the next run NemoClaw prompts again unless the credential is supplied through 1. Prefer short-lived or low-scope provider credentials where the upstream service supports them. 2. Rotate keys after suspected exposure, machine transfer, or account changes. 3. Prefer environment variables for ephemeral automation rather than registering long-lived secrets in the gateway. -4. Do not copy any host-side NemoClaw state into container images, Git repositories, bug reports, or support bundles. Even though credentials no longer live on disk, the surrounding configuration may reveal which providers you have registered. +4. Do not copy any host-side NemoClaw state into container images, Git repositories, bug reports, or support bundles. + Credentials no longer live on disk, but surrounding configuration may reveal which providers you have registered. 5. Keep your home directory private and owned by your user account. ## Related Files diff --git a/docs/security/openclaw-controls.mdx b/docs/security/openclaw-controls.mdx index 5c4bc1fce56..cfea9d4d207 100644 --- a/docs/security/openclaw-controls.mdx +++ b/docs/security/openclaw-controls.mdx @@ -14,7 +14,7 @@ It delegates all application-layer security to OpenClaw. This page documents areas where NemoClaw adds no independent protection beyond what OpenClaw already provides. The details below reflect the OpenClaw documentation at the time of writing. -Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security) for the current state. +Consult the [OpenClaw Security docs](https://docs.openclaw.ai/gateway/security) for current OpenClaw behavior. ## Prompt Injection Detection and Prevention @@ -22,12 +22,12 @@ OpenClaw detects and neutralizes prompt injection attempts before they reach the | Control | Detail | |---|---| -| Regex detection | Pattern matching detects common injection vectors such as "ignore all previous instructions" and `` tag spoofing | -| Boundary wrapping | Untrusted input is wrapped in randomized XML boundary markers | -| Unicode folding | Homoglyph folding normalizes bracket variants to prevent visual spoofing | -| Invisible character stripping | Zero-width invisible characters are removed from input | -| Boundary sanitization | Fake boundary markers are sanitized to prevent marker injection | -| Auto-wrapping | Web fetch and search results are automatically wrapped as untrusted external content | +| Regex detection | Pattern matching detects common injection vectors such as "ignore all previous instructions" and `` tag spoofing. | +| Boundary wrapping | OpenClaw wraps untrusted input in randomized XML boundary markers. | +| Unicode folding | Homoglyph folding normalizes bracket variants to prevent visual spoofing. | +| Invisible character stripping | OpenClaw removes zero-width invisible characters from input. | +| Boundary sanitization | OpenClaw sanitizes fake boundary markers to prevent marker injection. | +| Auto-wrapping | OpenClaw automatically wraps web fetch and search results as untrusted external content. | ## Tool Access Control and Policy Pipeline @@ -35,11 +35,11 @@ OpenClaw enforces a multi-layer tool policy pipeline that gates every tool call. | Control | Detail | |---|---| -| Deny list | High-risk tools (`exec`, `spawn`, `shell`, `fs_write`, `fs_delete`, and others) are blocked from Gateway HTTP by default | -| Policy pipeline | Multi-layer pipeline evaluates tool calls through profile, provider, agent, sandbox, and per-provider policies | -| Fail-closed semantics | Tool call hooks block execution on any error | -| Loop detection | Optional guard detects and blocks repeated identical tool call patterns (disabled by default, opt-in via `tools.loopDetection.enabled`) | -| Plugin approval | Approval workflow defaults to deny on timeout | +| Deny list | OpenClaw blocks high-risk tools (`exec`, `spawn`, `shell`, `fs_write`, `fs_delete`, and others) from Gateway HTTP by default. | +| Policy pipeline | The multi-layer pipeline evaluates tool calls through profile, provider, agent, sandbox, and per-provider policies. | +| Fail-closed semantics | Tool call hooks block execution on any error. | +| Loop detection | An optional guard detects and blocks repeated identical tool call patterns. It is disabled by default and opt-in via `tools.loopDetection.enabled`. | +| Plugin approval | The approval workflow defaults to deny on timeout. | ## Authentication Rate Limiting and Flood Protection @@ -47,10 +47,10 @@ OpenClaw rate-limits authentication attempts and guards against connection flood | Control | Detail | |---|---| -| Auth rate limiter | Sliding-window rate limiter tracks failed authentication attempts per IP and per scope | -| Control plane limiter | Per-device write rate limiting for control plane operations | -| WebSocket flood guard | Closes connections after repeated unauthorized attempts | -| Pre-auth budget | Limits connections before authentication completes | +| Auth rate limiter | A sliding-window rate limiter tracks failed authentication attempts per IP and per scope. | +| Control plane limiter | OpenClaw applies per-device write rate limiting for control plane operations. | +| WebSocket flood guard | OpenClaw closes connections after repeated unauthorized attempts. | +| Pre-auth budget | OpenClaw limits connections before authentication completes. | ## Environment Variable Security Policy @@ -58,17 +58,17 @@ OpenClaw blocks environment variables that could enable code injection, privileg | Category | Detail | |---|---| -| Always-blocked keys | Keys such as `NODE_OPTIONS`, `LD_PRELOAD`, shell injection vectors, crypto mining variables, and `GIT_*` hijacking paths | -| Override-blocked keys | Additional keys blocked unless explicitly overridden | -| Blocked prefixes | Prefixes such as `GIT_CONFIG_`, `NPM_CONFIG_`, `CARGO_REGISTRIES_`, `TF_VAR_` | -| Universal blocked prefixes | `DYLD_`, `LD_`, `BASH_FUNC_` | +| Always-blocked keys | OpenClaw blocks keys such as `NODE_OPTIONS`, `LD_PRELOAD`, shell injection vectors, crypto mining variables, and `GIT_*` hijacking paths. | +| Override-blocked keys | OpenClaw blocks additional keys unless you explicitly override them. | +| Blocked prefixes | OpenClaw blocks prefixes such as `GIT_CONFIG_`, `NPM_CONFIG_`, `CARGO_REGISTRIES_`, and `TF_VAR_`. | +| Universal blocked prefixes | OpenClaw blocks `DYLD_`, `LD_`, and `BASH_FUNC_`. | ## Security Audit Framework 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: +The following checks run as part of the audit: - Synced-folder leak detection. - Plaintext secrets in configuration files. @@ -101,11 +101,11 @@ OpenClaw controls who can interact with the agent through direct messages and gr | Control | Detail | |---|---| -| 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 | -| Multi-user detection | Heuristic that detects multi-user scenarios | +| DM policy modes | OpenClaw supports four modes: open, disabled, pairing, and allowlist. | +| Group policies | OpenClaw applies per-group access rules. | +| Per-sender authorization | OpenClaw gates individual senders. | +| Command authorization | OpenClaw applies command-level access control. | +| Multi-user detection | OpenClaw uses a heuristic that detects multi-user scenarios. | ## Context Visibility and Output Controls @@ -113,9 +113,9 @@ OpenClaw restricts what supplemental context the agent can see and how it can mo | Control | Detail | |---|---| -| Mode-based restrictions | Limits visibility of history, threads, quotes, and forwarded messages based on the active mode | -| Sender-based restrictions | Limits visibility based on who sent the message | -| Plugin output hooks | Plugin hooks intercept and modify tool results before they reach the user | +| Mode-based restrictions | OpenClaw limits visibility of history, threads, quotes, and forwarded messages based on the active mode. | +| Sender-based restrictions | OpenClaw limits visibility based on who sent the message. | +| Plugin output hooks | Plugin hooks intercept and modify tool results before they reach the user. | ## Safe Regex (ReDoS Prevention) diff --git a/fern/fern.config.json b/fern/fern.config.json index a63e093419f..c40e5d23b81 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "nvidia", - "version": "5.50.5" + "version": "5.55.0" } From fb1bc63f641084fe45cd8b3040303e2bfa241e88 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 26 Jun 2026 11:02:34 -0700 Subject: [PATCH 2/4] docs: clarify forward references Signed-off-by: Miyoung Choi --- docs/about/ecosystem-hermes.mdx | 2 +- docs/about/ecosystem.mdx | 2 +- docs/get-started/quickstart-hermes.mdx | 2 +- docs/manage-sandboxes/runtime-controls.mdx | 2 +- docs/reference/platform-support.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/about/ecosystem-hermes.mdx b/docs/about/ecosystem-hermes.mdx index 1704522323e..ecfaba53bcc 100644 --- a/docs/about/ecosystem-hermes.mdx +++ b/docs/about/ecosystem-hermes.mdx @@ -85,7 +85,7 @@ The following table compares custom OpenShell integration with `nemohermes onboa ## When to Use Which -Use this table to choose NemoHermes or OpenShell. +Use the following table to choose NemoHermes or OpenShell. | Situation | Prefer | |-----------|--------| diff --git a/docs/about/ecosystem.mdx b/docs/about/ecosystem.mdx index 00cb8ac4520..729126328ea 100644 --- a/docs/about/ecosystem.mdx +++ b/docs/about/ecosystem.mdx @@ -85,7 +85,7 @@ The following table compares the two paths. ## When to Use Which -Use this table to choose NemoClaw or OpenShell. +Use the following table to choose NemoClaw or OpenShell. | Situation | Prefer | |-----------|--------| diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index 9666d30962f..8a1321b6ad7 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -86,7 +86,7 @@ Hermes uses an agent-specific baseline policy that allows the Hermes binary and ## Use Non-Interactive Setup For CI or scripted installs, set the required environment variables before running the installer. -This example uses NVIDIA Endpoints and creates a sandbox named `my-hermes`. +The following example uses NVIDIA Endpoints and creates a sandbox named `my-hermes`. ```bash export NEMOCLAW_AGENT=hermes diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx index fb5608a168a..e0c70b2dd41 100644 --- a/docs/manage-sandboxes/runtime-controls.mdx +++ b/docs/manage-sandboxes/runtime-controls.mdx @@ -18,7 +18,7 @@ This page explains which parts of a running NemoClaw sandbox can change immediat ## What You Can Change at Runtime NemoClaw applies its security posture in three layers: what onboarding writes into the sandbox image, what the running sandbox can hot-reload, and what requires a rebuild or re-onboard. -This table maps each commonly changed item to the layer that owns it and the command that changes it. +The following table maps each commonly changed item to the layer that owns it and the command that changes it. diff --git a/docs/reference/platform-support.mdx b/docs/reference/platform-support.mdx index e0c337a4f77..636755ae825 100644 --- a/docs/reference/platform-support.mdx +++ b/docs/reference/platform-support.mdx @@ -141,7 +141,7 @@ Each row below is a launch-facing capability claim that NemoClaw makes in docs, ## Deployment Paths -Use this section to choose how to bring up NemoClaw on a host. +Use the following table to choose how to bring up NemoClaw on a host. Pick the row that matches the target environment. {/* deployment-status:begin */} From d239935ae89a2889aed1c8951439ecd74414e189 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 26 Jun 2026 11:07:15 -0700 Subject: [PATCH 3/4] docs: remove dash punctuation from prose Signed-off-by: Miyoung Choi --- docs/reference/commands-nemohermes.mdx | 25 ++++++++++++------- docs/reference/commands.mdx | 34 +++++++++++++++++--------- 2 files changed, 38 insertions(+), 21 deletions(-) diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 1add6a8251f..4edadc2ac46 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -247,7 +247,7 @@ Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is dete Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state declared by the selected agent profile and restores it into the new sandbox once it is live. This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass `NEMOCLAW_RECREATE_SANDBOX=1` no longer drop user files from the selected agent workspace. The behaviour matches `nemohermes rebuild --force`. -NemoClaw aborts the recreate when the backup cannot complete in full — including when individual state directories or files fail mid-backup — so failed entries are not silently dropped on delete. +NemoClaw aborts the recreate when the backup cannot complete in full, including when individual state directories or files fail mid-backup, so failed entries are not silently dropped on delete. Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup. The destination sandbox starts with a fresh workspace. @@ -565,10 +565,10 @@ Use that line to distinguish a healthy backend from a broken proxy path that the For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. -When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints `Failure layer: docker_unreachable — Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status. +When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints the `docker_unreachable` failure layer with the message `Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status. -When the host Docker daemon is reachable but the per-sandbox container is stopped, the command prints `Failure layer: sandbox_container_stopped — sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. -If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to `Failure layer: sandbox_dashboard_port_conflict — sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. +When the host Docker daemon is reachable but the per-sandbox container is stopped, the command prints the `sandbox_container_stopped` failure layer with the message `sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. +If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. When a locally registered sandbox is missing from the live gateway, status preserves the registry entry so the suggested `rebuild --yes` recovery can still find the sandbox metadata. @@ -891,7 +891,8 @@ Channels fall into three login modes: This intentionally leaves QR-created mutable session state in the sandbox until you unpair it or clear the durable agent state. After registering the channel, NemoClaw asks whether to rebuild immediately. -Running `add` for an already-configured channel simply overwrites the stored credentials where applicable — the operation is idempotent. +Running `add` for an already-configured channel overwrites the stored credentials where applicable. +The operation is idempotent. Channel names are trimmed and lowercased before NemoClaw stores credentials, names bridge providers, or prints rebuild messages. NemoClaw requires the matching built-in network policy preset YAML to be present. A missing or malformed preset YAML (no `network_policies:` section) aborts `channels add` before any token prompt, registry write, or rebuild prompt. @@ -914,7 +915,8 @@ Slack requires both `SLACK_BOT_TOKEN` (bot user OAuth) and `SLACK_APP_TOKEN` (ap Optional Slack allowlists come from `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` at rebuild time. Telegram and Discord mention mode default to `1` when no environment, session, or saved state value exists for that setting. Discord applies that default only when a server ID is configured. -When `NEMOCLAW_NON_INTERACTIVE=1` is set, any missing token fails fast and no rebuild prompt is shown — instead, the change is queued and you are told to run `nemohermes rebuild` manually. +When `NEMOCLAW_NON_INTERACTIVE=1` is set, any missing token fails fast and no rebuild prompt is shown. +Instead, the change is queued and you are told to run `nemohermes rebuild` manually. If you omit the required `` argument, the CLI prints the `channels add ` usage with the supported channel list instead of falling back to top-level help. ### `nemohermes channels remove ` @@ -1305,7 +1307,8 @@ The selector accepts any of: - An exact timestamp. Pass `--to ` to restore the snapshot into a different sandbox instead of the source. -When `dst` does not exist, it is auto-created by reusing the source sandbox's container image — no re-onboarding needed. +When `dst` does not exist, it is auto-created by reusing the source sandbox's container image. +No re-onboarding is needed. When `dst` already exists, `snapshot restore --to ` refuses by default to avoid silently mutating the destination's filesystem. To overwrite an existing destination, pass `--force`: the command deletes `dst`, then recreates it from the source's image and restores the snapshot into the fresh copy. The `--force` path prompts interactively to confirm the destination name before deleting. @@ -1572,7 +1575,11 @@ nemohermes debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH] If `--output` is set and the tarball cannot be written (for example, the destination directory is missing or read-only), the command exits non-zero so scripts can detect the failure. The tarball is written to a temporary sibling and renamed on success, so a pre-existing file at `--output` is preserved when `tar` fails. -When `--sandbox` is supplied explicitly (via flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, `SANDBOX_NAME` — flag wins, then the env vars in that order), the name must match a registered sandbox; if `openshell sandbox list` succeeds it must also appear in the live gateway. An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written. Without an explicit name, `nemohermes debug` falls back to the registry's default sandbox (and warns if that default is stale). +When `--sandbox` is supplied explicitly through the flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, or `SANDBOX_NAME`, the name must match a registered sandbox. +The flag wins, then the env vars in that order. +If `openshell sandbox list` succeeds, the sandbox must also appear in the live gateway. +An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written. +Without an explicit name, `nemohermes debug` falls back to the registry's default sandbox and warns if that default is stale. ### `nemohermes credentials list` @@ -1951,7 +1958,7 @@ The following flags change defaults for commands that manage existing sandboxes. | `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `nemohermes destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. | | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `nemohermes connect` and `nemohermes connect --probe-only`. Use only as a troubleshooting escape hatch. | | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. | -| `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0`–`10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `nemohermes shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it — the best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. | +| `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0` to `10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `nemohermes shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. | ### Legacy `nemohermes setup` diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 065a597ae8b..e64636e6f3e 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -329,7 +329,7 @@ Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is dete Before deleting an existing sandbox during recreation, NemoClaw backs up the workspace state declared by the selected agent profile and restores it into the new sandbox once it is live. This applies whether the existing sandbox is ready or marked not-ready, so cross-version upgrades that pass `NEMOCLAW_RECREATE_SANDBOX=1` no longer drop user files from the selected agent workspace. The behaviour matches `$$nemoclaw rebuild --force`. -NemoClaw aborts the recreate when the backup cannot complete in full — including when individual state directories or files fail mid-backup — so failed entries are not silently dropped on delete. +NemoClaw aborts the recreate when the backup cannot complete in full, including when individual state directories or files fail mid-backup, so failed entries are not silently dropped on delete. Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup. The destination sandbox starts with a fresh workspace. @@ -572,7 +572,9 @@ Use this when driving the sandbox programmatically from another process (CI job, All flags accepted by the selected in-sandbox agent CLI are forwarded verbatim, so the upstream surface stays the single source of truth. -OpenClaw invocations must include at least one target selector — `--agent`, `--session-id`, `--session-key`, or `--to` — so the wrapper never falls back to the unspecified default-session behaviour. Conflict resolution between multiple selectors is delegated to the in-sandbox `openclaw agent` argv contract; the host-side guard only checks presence. +OpenClaw invocations must include at least one target selector: `--agent`, `--session-id`, `--session-key`, or `--to`. +This keeps the wrapper from falling back to the unspecified default-session behaviour. +Conflict resolution between multiple selectors is delegated to the in-sandbox `openclaw agent` argv contract; the host-side guard only checks presence. ```bash $$nemoclaw my-assistant agent --agent work -m "Summarise README.md" @@ -598,7 +600,7 @@ For registered terminal-runtime sandboxes, bare invocations and `--help` are for Host-side validation runs before the sandbox dispatch: -- OpenClaw sandboxes and registry fallbacks must include at least one target selector flag — `--agent`, `--session-id`, `--session-key`, or `--to` (in either `--flag value` or `--flag=value` form). OpenClaw invocations without a selector exit `2` and print `No target session selected` locally, without paying the in-sandbox dispatch cost. Registered terminal-runtime sandboxes delegate bare invocations and help flags to the manifest command instead. +- OpenClaw sandboxes and registry fallbacks must include at least one target selector flag: `--agent`, `--session-id`, `--session-key`, or `--to` in either `--flag value` or `--flag=value` form. OpenClaw invocations without a selector exit `2` and print `No target session selected` locally, without paying the in-sandbox dispatch cost. Registered terminal-runtime sandboxes delegate bare invocations and help flags to the manifest command instead. - If the sandbox is registered but not in a `Ready` or `Running` phase, the wrapper exits `1` and prints the documented recovery commands (`$$nemoclaw recover`, `$$nemoclaw rebuild --yes`, `$$nemoclaw onboard --resume`) rather than deferring the readiness rejection to `openshell sandbox exec`. @@ -717,10 +719,10 @@ Use that line to distinguish a healthy backend from a broken proxy path that the For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. -When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints `Failure layer: docker_unreachable — Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status. +When the sandbox's recorded driver is `docker` and the host Docker daemon is not reachable, the command prints the `docker_unreachable` failure layer with the message `Docker daemon is not reachable.` as the first line of stdout, suppresses the host-side `Inference` probe (which otherwise hits the remote provider directly and is misleading when the local stack is down), and exits with a non-zero status. -When the host Docker daemon is reachable but the per-sandbox container is stopped, the command prints `Failure layer: sandbox_container_stopped — sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. -If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to `Failure layer: sandbox_dashboard_port_conflict — sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. +When the host Docker daemon is reachable but the per-sandbox container is stopped, the command prints the `sandbox_container_stopped` failure layer with the message `sandbox container exists but is not running.` as the first line of stdout, suppresses the host-side `Inference` probe, and exits with a non-zero status. +If the sandbox's recorded dashboard port is also held by a foreign listener, the header escalates to the `sandbox_dashboard_port_conflict` failure layer with the message `sandbox container is stopped and the dashboard port is held by a foreign listener.` so the operator can recover the port before restarting the sandbox. If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. When a locally registered sandbox is missing from the live gateway, status preserves the registry entry so the suggested `rebuild --yes` recovery can still find the sandbox metadata. @@ -751,7 +753,8 @@ $$nemoclaw my-assistant status NemoClaw pins the OpenClaw version inside the sandbox at build time, not at runtime. The NemoClaw runtime build target is declared by `OPENCLAW_VERSION` in the NemoClaw Dockerfiles. The `min_openclaw_version` field in `nemoclaw-blueprint/blueprint.yaml` remains the compatibility floor for direct blueprint consumers, so it can be lower than the Dockerfile target. -Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer pin — you upgrade by rebuilding the sandbox. +Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer pin. +Upgrade by rebuilding the sandbox. `$$nemoclaw status` prints the running OpenClaw version on the `Agent` line: @@ -1160,7 +1163,8 @@ Channels fall into three login modes: This intentionally leaves QR-created mutable session state in the sandbox until you unpair it or clear the durable agent state. After registering the channel, NemoClaw asks whether to rebuild immediately. -Running `add` for an already-configured channel simply overwrites the stored credentials where applicable — the operation is idempotent. +Running `add` for an already-configured channel overwrites the stored credentials where applicable. +The operation is idempotent. Channel names are trimmed and lowercased before NemoClaw stores credentials, names bridge providers, or prints rebuild messages. NemoClaw requires the matching built-in network policy preset YAML to be present. A missing or malformed preset YAML (no `network_policies:` section) aborts `channels add` before any token prompt, registry write, or rebuild prompt. @@ -1183,7 +1187,8 @@ Slack requires both `SLACK_BOT_TOKEN` (bot user OAuth) and `SLACK_APP_TOKEN` (ap Optional Slack allowlists come from `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` at rebuild time. Telegram and Discord mention mode default to `1` when no environment, session, or saved state value exists for that setting. Discord applies that default only when a server ID is configured. -When `NEMOCLAW_NON_INTERACTIVE=1` is set, any missing token fails fast and no rebuild prompt is shown — instead, the change is queued and you are told to run `$$nemoclaw rebuild` manually. +When `NEMOCLAW_NON_INTERACTIVE=1` is set, any missing token fails fast and no rebuild prompt is shown. +Instead, the change is queued and you are told to run `$$nemoclaw rebuild` manually. If you omit the required `` argument, the CLI prints the `channels add ` usage with the supported channel list instead of falling back to top-level help. ### `$$nemoclaw channels remove ` @@ -1638,7 +1643,8 @@ The selector accepts any of: - An exact timestamp. Pass `--to ` to restore the snapshot into a different sandbox instead of the source. -When `dst` does not exist, it is auto-created by reusing the source sandbox's container image — no re-onboarding needed. +When `dst` does not exist, it is auto-created by reusing the source sandbox's container image. +No re-onboarding is needed. When `dst` already exists, `snapshot restore --to ` refuses by default to avoid silently mutating the destination's filesystem. To overwrite an existing destination, pass `--force`: the command deletes `dst`, then recreates it from the source's image and restores the snapshot into the fresh copy. The `--force` path prompts interactively to confirm the destination name before deleting. @@ -1923,7 +1929,11 @@ $$nemoclaw debug [--quick|-q] [--sandbox NAME] [--output PATH|-o PATH] If `--output` is set and the tarball cannot be written (for example, the destination directory is missing or read-only), the command exits non-zero so scripts can detect the failure. The tarball is written to a temporary sibling and renamed on success, so a pre-existing file at `--output` is preserved when `tar` fails. -When `--sandbox` is supplied explicitly (via flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, `SANDBOX_NAME` — flag wins, then the env vars in that order), the name must match a registered sandbox; if `openshell sandbox list` succeeds it must also appear in the live gateway. An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written. Without an explicit name, `$$nemoclaw debug` falls back to the registry's default sandbox (and warns if that default is stale). +When `--sandbox` is supplied explicitly through the flag or one of `NEMOCLAW_SANDBOX_NAME`, `NEMOCLAW_SANDBOX`, or `SANDBOX_NAME`, the name must match a registered sandbox. +The flag wins, then the env vars in that order. +If `openshell sandbox list` succeeds, the sandbox must also appear in the live gateway. +An unknown or stale name exits non-zero with an actionable error that names the sandbox and reports the source env var when applicable, and no tarball is written. +Without an explicit name, `$$nemoclaw debug` falls back to the registry's default sandbox and warns if that default is stale. ### `$$nemoclaw credentials list` @@ -2397,7 +2407,7 @@ The following flags change defaults for commands that manage existing sandboxes. | `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `$$nemoclaw destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. | | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `$$nemoclaw connect` and `$$nemoclaw connect --probe-only`. Use only as a troubleshooting escape hatch. | | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. | -| `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0`–`10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `$$nemoclaw shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it — the best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. | +| `NEMOCLAW_SHIELDS_SETTLE_MS` | milliseconds (default `750`, clamped to `0` to `10000`) | Settle window NemoClaw waits after re-applying a config lockdown (during shields auto-restore and `$$nemoclaw shields up` drift remediation) before re-confirming the lock still holds. Detects when an in-sandbox reconciler changes config file permissions after lockdown and re-applies the lock; if NemoClaw cannot re-confirm the lock within the retry budget, shields stay down. This narrows the window in which a reconciler can revert permissions rather than eliminating it. The best-effort `chattr +i` immutable bit remains the only fully durable lock. Raise it on hosts where the gateway settles slowly. | ### Remote Deployment From 0fb22055885a7be98d3f366623dea11747260d0e Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Fri, 26 Jun 2026 11:13:59 -0700 Subject: [PATCH 4/4] docs: prefer refer-to cross references Signed-off-by: Miyoung Choi --- docs/about/ecosystem.mdx | 2 +- docs/about/how-it-works.mdx | 2 +- docs/about/overview.mdx | 2 +- docs/about/release-notes.mdx | 2 +- docs/deployment/brev-web-ui.mdx | 2 +- docs/deployment/install-openclaw-plugins.mdx | 2 +- docs/get-started/prerequisites.mdx | 2 +- docs/get-started/windows-preparation.mdx | 2 +- .../inference/declarative-agents-manifest.mdx | 2 +- docs/inference/inference-options.mdx | 6 ++-- docs/inference/use-local-inference.mdx | 2 +- docs/manage-sandboxes/backup-restore.mdx | 2 +- .../install-plugins-hermes.mdx | 4 +-- docs/manage-sandboxes/lifecycle.mdx | 24 +++++++------- docs/manage-sandboxes/messaging-channels.mdx | 4 +-- docs/manage-sandboxes/runtime-controls.mdx | 6 ++-- docs/manage-sandboxes/workspace-files.mdx | 2 +- docs/monitoring/monitor-sandbox-activity.mdx | 2 +- .../customize-network-policy.mdx | 6 ++-- .../integration-policy-examples.mdx | 2 +- docs/reference/architecture.mdx | 2 +- docs/reference/commands-nemohermes.mdx | 21 ++++++------ docs/reference/commands.mdx | 32 ++++++++++--------- docs/reference/enterprise-readiness.mdx | 30 ++++++++--------- docs/reference/network-policies.mdx | 2 +- docs/reference/platform-support.mdx | 6 ++-- docs/reference/troubleshooting.mdx | 18 +++++------ docs/resources/license.mdx | 2 +- docs/security/best-practices.mdx | 10 +++--- docs/security/credential-storage.mdx | 2 +- 30 files changed, 103 insertions(+), 100 deletions(-) diff --git a/docs/about/ecosystem.mdx b/docs/about/ecosystem.mdx index 729126328ea..14b34da1981 100644 --- a/docs/about/ecosystem.mdx +++ b/docs/about/ecosystem.mdx @@ -73,7 +73,7 @@ The following table compares the two paths. | Capability | `openshell sandbox create --from openclaw` | `nemoclaw onboard` | |---|---|---| -| Sandbox isolation | Yes. OpenShell applies seccomp filters, Landlock filesystem restrictions, privilege dropping, network namespace isolation, and no-new-privileges enforcement. The community sandbox bundles its own policy tailored for OpenClaw. | Yes. NemoClaw applies these through the blueprint and layers a more restrictive policy on top (see rows below). | +| Sandbox isolation | Yes. OpenShell applies seccomp filters, Landlock filesystem restrictions, privilege dropping, network namespace isolation, and no-new-privileges enforcement. The community sandbox bundles its own policy tailored for OpenClaw. | Yes. NemoClaw applies these through the blueprint and layers a more restrictive policy on top (refer to rows below). | | 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 removes 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. | diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 2d0b8e143f5..1adb837cf5c 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -43,7 +43,7 @@ The diagram has the following components: | 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](../reference/architecture). +For repository layout, file paths, and deeper diagrams, refer to [Architecture](../reference/architecture). ## Design Principles diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 65ce1827acc..6bc9e739078 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -53,7 +53,7 @@ NemoClaw provides these benefits to mitigate those risks. | Benefit | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------| | Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. The sandbox grants no access by default. | -| Routed inference | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. See [Inference Options](../inference/inference-options). | +| 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. | diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index e13a1d582af..52f2ded7f26 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -441,4 +441,4 @@ NemoClaw pins the OpenClaw version inside the sandbox at build time via `OPENCLA The `min_openclaw_version` field in `nemoclaw-blueprint/blueprint.yaml` is the compatibility floor for direct blueprint consumers and may be lower than the NemoClaw runtime target. Existing sandboxes do not auto-upgrade. Run `nemoclaw status` to see the OpenClaw version currently running in a sandbox, and `nemoclaw rebuild` to pick up a newer pin from a NemoClaw upgrade. -See [Checking the OpenClaw version](../reference/commands#checking-the-openclaw-version) for the full policy. +Refer to [Checking the OpenClaw version](../reference/commands#checking-the-openclaw-version) for the full policy. diff --git a/docs/deployment/brev-web-ui.mdx b/docs/deployment/brev-web-ui.mdx index 7df1f2af87b..a60cd0452a4 100644 --- a/docs/deployment/brev-web-ui.mdx +++ b/docs/deployment/brev-web-ui.mdx @@ -14,7 +14,7 @@ Brev provisions a remote VM, configures inference, starts OpenClaw inside an Ope Use this guide when you want to try NemoClaw without installing the CLI or using a local GPU. -If you want to manage the remote host from a terminal, see [Deploy to a Remote GPU Instance](deploy-to-remote-gpu). +If you want to manage the remote host from a terminal, refer to [Deploy to a Remote GPU Instance](deploy-to-remote-gpu). ## What This Flow Creates diff --git a/docs/deployment/install-openclaw-plugins.mdx b/docs/deployment/install-openclaw-plugins.mdx index fa17a12d5ce..1f4396b107e 100644 --- a/docs/deployment/install-openclaw-plugins.mdx +++ b/docs/deployment/install-openclaw-plugins.mdx @@ -111,7 +111,7 @@ Order Dockerfile instructions from least-changing to most-changing so warm rebui Pin the base image to an explicit tag or digest so warm rebuilds resolve the same cached base instead of pulling a new one. When a build is slow, set `NEMOCLAW_TRACE=1` before onboarding to capture phase timings that separate context staging, Docker build, image upload, and sandbox readiness. -For the full `--from` build-context rules and trace details, see [CLI Commands Reference](../reference/commands). +For the full `--from` build-context rules and trace details, refer to [CLI Commands Reference](../reference/commands). ## Network Access diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index 19c697efcd2..3d83e382c73 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -32,7 +32,7 @@ If you cannot add memory, configure at least 8 GB of swap to work around the iss | Node.js | 22.16 or later | | npm | 10 or later | | Docker | Docker Engine, Docker Desktop, or Colima on a tested platform | -| Platform | See [Platforms](#platforms) below | +| Platform | Refer to [Platforms](#platforms) below | 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. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index f288109334d..4abe687d7f2 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -183,4 +183,4 @@ All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, see the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide. +For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](../../reference/troubleshooting#windows-subsystem-for-linux) in the Troubleshooting guide. diff --git a/docs/inference/declarative-agents-manifest.mdx b/docs/inference/declarative-agents-manifest.mdx index c970f683c1a..701b3467fdd 100644 --- a/docs/inference/declarative-agents-manifest.mdx +++ b/docs/inference/declarative-agents-manifest.mdx @@ -100,7 +100,7 @@ Operators cannot set `default: true` on a secondary agent and cannot rename the | `tools` | yes | `{profile?, allow?, deny?}`. Must declare a non-empty `allow[]` or `deny[]`; secondary agents inherit no tools by default. | | `description` | no | Human-readable. Baked verbatim. | | `model` | no | `provider/model` reference. The provider must match the onboard provider; cross-provider manifests are not supported. | -| `subagents` | no | OpenClaw-native sub-agent delegation policy. See below. | +| `subagents` | no | OpenClaw-native sub-agent delegation policy. Refer to the section below. | ### Sub-Agent Delegation Block diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index fe69399297d..c57e9f5585c 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -66,9 +66,9 @@ The managed install/start vLLM entry appears by default on DGX Spark and DGX Sta |--------|-------------|----------------| | NVIDIA Endpoints | Routes to models hosted on [build.nvidia.com](https://build.nvidia.com). You can also enter any model ID from the catalog. Set `NVIDIA_INFERENCE_API_KEY`. | Nemotron 3 Super 120B, Nemotron 3 Ultra 550B, GLM-5.1, MiniMax M2.7, GPT-OSS 120B, DeepSeek V4 Pro | | OpenAI | Routes to the OpenAI API. Set `OPENAI_API_KEY`. | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-pro-2026-03-05` | -| Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. NemoClaw uses `/v1/chat/completions` at runtime by default; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` for proxies that implement it, such as some llama.cpp builds. The wizard prompts for a base URL and model name. The adapter is validated against OpenRouter (see the status table above); behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations such as LocalAI or llama.cpp may vary. When you enable Telegram messaging, onboarding also runs a bounded sandbox-side smoke check through `https://inference.local/v1/chat/completions`. Set `COMPATIBLE_API_KEY`. | You provide the model name. | +| Other OpenAI-compatible endpoint | Routes to any server that implements `/v1/chat/completions`. NemoClaw uses `/v1/chat/completions` at runtime by default; set `NEMOCLAW_PREFERRED_API=openai-responses` to allow `/v1/responses` for proxies that implement it, such as some llama.cpp builds. The wizard prompts for a base URL and model name. The adapter is validated against OpenRouter (refer to the status table above); behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations such as LocalAI or llama.cpp may vary. When you enable Telegram messaging, onboarding also runs a bounded sandbox-side smoke check through `https://inference.local/v1/chat/completions`. Set `COMPATIBLE_API_KEY`. | You provide the model name. | | Anthropic | Routes to the Anthropic Messages API. Set `ANTHROPIC_API_KEY`. | `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6` | -| Other Anthropic-compatible endpoint | Routes to any server that implements the Anthropic Messages API (`/v1/messages`). The adapter is validated against AWS Bedrock (see the status table above); behavior on other Anthropic-compatible proxies and gateways may vary. The wizard prompts for a base URL and model name. Set `COMPATIBLE_ANTHROPIC_API_KEY`. | You provide the model name. | +| Other Anthropic-compatible endpoint | Routes to any server that implements the Anthropic Messages API (`/v1/messages`). The adapter is validated against AWS Bedrock (refer to the status table above); behavior on other Anthropic-compatible proxies and gateways may vary. The wizard prompts for a base URL and model name. Set `COMPATIBLE_ANTHROPIC_API_KEY`. | You provide the model name. | | Google Gemini | Routes to Google's OpenAI-compatible chat-completions endpoint. NemoClaw skips the Responses-API probe because Gemini does not support `/v1/responses`. Set `GEMINI_API_KEY`. | `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` | | Hermes Provider | Routes Hermes Agent through the host OpenShell provider registered by NemoClaw when onboarding Hermes Agent. | Curated Hermes Provider models such as `moonshotai/kimi-k2.6`, `openai/gpt-5.4-mini`, and `z-ai/glm-5.1`. | | Local Ollama | Routes to a local Ollama instance on `localhost:11434`. NemoClaw detects installed models, offers starter models if none are present, pulls and warms the selected model, and validates it. | Selected during onboarding. For more information, refer to [Use a Local Inference Server](use-local-inference). | @@ -176,7 +176,7 @@ An already-running vLLM server appears directly in the onboarding selection list | 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 when vLLM is already running. Can install or start a managed vLLM container by default on DGX Spark/Station and after opt-in on generic Linux NVIDIA GPU hosts. | -For setup instructions, see [Use a Local Inference Server](use-local-inference). +For setup instructions, refer to [Use a Local Inference Server](use-local-inference). ## Validation diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index 67f4a070a72..415e3dd29a4 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -117,7 +117,7 @@ Selecting one of those actions in the unsupported native Docker topology exits e Ollama is convenient for local chat, but some model/template combinations can return tool calls as plain text under realistic agent load. If the TUI shows raw JSON such as `{"name":"memory_search","arguments":{...}}` instead of running a tool, switch to vLLM with `--enable-auto-tool-choice` and the correct `--tool-call-parser`. -See [Tool-Calling Reliability](tool-calling-reliability). +Refer to [Tool-Calling Reliability](tool-calling-reliability). diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index 68cfc25fb80..9a87c18cdf2 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -96,7 +96,7 @@ NemoClaw-regenerated Hermes config files, including `config.yaml` and `.env`, ar NemoClaw recreates model/provider and messaging credentials from host-side onboarding and OpenShell provider state during rebuild. -For full details, see the [Commands reference](../reference/commands). +For full details, refer to the [Commands reference](../reference/commands). ## Manual Backup diff --git a/docs/manage-sandboxes/install-plugins-hermes.mdx b/docs/manage-sandboxes/install-plugins-hermes.mdx index 322db32eb76..5ce81332c94 100644 --- a/docs/manage-sandboxes/install-plugins-hermes.mdx +++ b/docs/manage-sandboxes/install-plugins-hermes.mdx @@ -108,8 +108,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. -See [Network Policies](../reference/network-policies) for policy concepts. -See [Customize Network Policy](../network-policy/customize-network-policy) for custom preset workflows. +Refer to [Network Policies](../reference/network-policies) for policy concepts. +Refer to [Customize Network Policy](../network-policy/customize-network-policy) for custom preset workflows. ## Common Mistakes diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index 0f746805fca..0cc57c357e2 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -21,10 +21,10 @@ Use this guide after you finish [Quickstart with Hermes](../get-started/quicksta It covers ongoing sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. -When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw` and `openshell`. +When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw` and `openshell`. -When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw`, `nemoclaw`, and `openshell`. +When a workflow uses the lower-level OpenShell CLI, refer to [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `$$nemoclaw`, `nemoclaw`, and `openshell`. ## List Sandboxes @@ -153,7 +153,7 @@ Change the active model or provider at runtime without rebuilding the sandbox: $$nemoclaw inference set --model --provider ``` -See [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. +Refer to [Switch Inference Providers](../inference/switch-inference-providers) for provider-specific model IDs and API compatibility notes. ### Restart the Gateway and Port Forward @@ -170,7 +170,7 @@ $$nemoclaw recover The command restarts the in-sandbox gateway and re-establishes the dashboard port-forward in one step. It is idempotent and safe to script. -See [`$$nemoclaw recover`](../reference/commands#$$nemoclaw-name-recover) for details. +Refer to [`$$nemoclaw recover`](../reference/commands#$$nemoclaw-name-recover) for details. ### Reset a Stored Credential @@ -182,7 +182,7 @@ $$nemoclaw credentials reset # clear a single provider, for exampl $$nemoclaw onboard # re-run to re-enter the cleared provider ``` -See [`$$nemoclaw credentials reset `](../reference/commands#$$nemoclaw-credentials-reset-provider) for full command details. +Refer to [`$$nemoclaw credentials reset `](../reference/commands#$$nemoclaw-credentials-reset-provider) for full command details. ### Rebuild a Sandbox While Preserving Workspace State @@ -199,7 +199,7 @@ $$nemoclaw rebuild The rebuild command preserves the mounted workspace and registered policies while recreating the container. If NemoClaw cannot archive any requested state path, it reports the backup failure and stops before deleting the original sandbox. -See [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for flag details. +Refer to [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for flag details. ### Add a Network Preset After Onboarding @@ -209,11 +209,11 @@ Apply an additional preset, such as Telegram or GitHub, to a running sandbox wit $$nemoclaw policy-add ``` -See [`$$nemoclaw policy-add`](../reference/commands#$$nemoclaw-name-policy-add) for usage details and flags. +Refer to [`$$nemoclaw policy-add`](../reference/commands#$$nemoclaw-name-policy-add) for usage details and flags. Non-interactive re-onboards in the default `suggested` policy mode preserve presets added this way. To make a re-onboard authoritative, set `NEMOCLAW_POLICY_MODE=custom` and provide `NEMOCLAW_POLICY_PRESETS` with the exact list to apply; onboarding removes anything else. -See [`NEMOCLAW_POLICY_MODE`](../reference/commands#$$nemoclaw-onboard) for the full table. +Refer to [`NEMOCLAW_POLICY_MODE`](../reference/commands#$$nemoclaw-onboard) for the full table. ## Update to the Maintained Version @@ -239,8 +239,8 @@ Each rebuild destroys the old container and creates a new one, while preserving `upgrade-sandboxes --check` can report a sandbox as stale because the running agent version is behind, because the managed NemoClaw image fingerprint differs from the current CLI, or both. Custom-image sandboxes created with `--from ` are not marked stale solely by image fingerprint, so an upgrade check does not accidentally replace them with the default image. Runtime changes outside those state paths, such as packages installed manually in the running container, are not preserved. -See [Backup and Restore](backup-restore) for the full state-preservation contract, snapshot restore behavior, and manual backup workflow. -See [`$$nemoclaw update`](../reference/commands#$$nemoclaw-update), [`$$nemoclaw upgrade-sandboxes`](../reference/commands#$$nemoclaw-upgrade-sandboxes), and [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for command flags. +Refer to [Backup and Restore](backup-restore) for the full state-preservation contract, snapshot restore behavior, and manual backup workflow. +Refer to [`$$nemoclaw update`](../reference/commands#$$nemoclaw-update), [`$$nemoclaw upgrade-sandboxes`](../reference/commands#$$nemoclaw-upgrade-sandboxes), and [`$$nemoclaw rebuild`](../reference/commands#$$nemoclaw-name-rebuild) for command flags. ## Uninstall @@ -261,7 +261,7 @@ The uninstall command preserves `~/.nemoclaw/rebuild-backups/` (host-side snapsh Uninstall removes every other entry under `~/.nemoclaw/`. Interactive runs prompt before they remove the preserved entries; the default answer keeps them. For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well. -See the [Commands reference](../reference/commands#$$nemoclaw-uninstall) for the full preservation contract. +Refer to the [Commands reference](../reference/commands#$$nemoclaw-uninstall) for the full preservation contract. The CLI uninstall command runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. @@ -278,7 +278,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 ``` -See [`$$nemoclaw uninstall` vs. the hosted `uninstall.sh`](../reference/commands#$$nemoclaw-uninstall-vs-the-hosted-uninstallsh) for a full comparison of what the two forms 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) for a full comparison of what the two forms fetch, what they trust, and when to prefer each. ## Related Topics diff --git a/docs/manage-sandboxes/messaging-channels.mdx b/docs/manage-sandboxes/messaging-channels.mdx index c6053a9b918..56f320c52cc 100644 --- a/docs/manage-sandboxes/messaging-channels.mdx +++ b/docs/manage-sandboxes/messaging-channels.mdx @@ -44,7 +44,7 @@ It only starts optional host services such as the cloudflared tunnel when that b `$$nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. It only starts optional host services such as the cloudflared tunnel when that binary is present. -See [Commands](../reference/commands) for details. +Refer to [Commands](../reference/commands) for details. ## Prerequisites @@ -302,7 +302,7 @@ Use `channels remove wechat` first if you intend to acquire a fresh account. Running `channels add` for a channel that is already configured overwrites the stored tokens and registers the updated bridge provider. For WeChat the cached-token short-circuit applies. -See [`channels add wechat`](#channels-add-wechat) for how to acquire a fresh account. +Refer to [`channels add wechat`](#channels-add-wechat) for how to acquire a fresh account. Rebuild the sandbox after the update so the image reflects the current channel set. To remove a channel and clear its stored credentials, run: diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx index e0c70b2dd41..9b21d600116 100644 --- a/docs/manage-sandboxes/runtime-controls.mdx +++ b/docs/manage-sandboxes/runtime-controls.mdx @@ -30,9 +30,9 @@ The following table maps each commonly changed item to the layer that owns it an | 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 | +| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`openclaw.json` is the source of truth at runtime, refer to #3453) | `$$nemoclaw channels stop ` then rebuild | | Dashboard forward port | Runtime. Port is re-resolved on next `connect` | `NEMOCLAW_DASHBOARD_PORT= $$nemoclaw connect` | -| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 $$nemoclaw connect` (see #3259) | +| Dashboard bind address (loopback compared to all interfaces) | Runtime. Applies on next `connect` | `NEMOCLAW_DASHBOARD_BIND=0.0.0.0 $$nemoclaw connect` (refer to #3259) | | Default OpenClaw workspace template seed (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`) | Locked at first sandbox boot. Re-onboard required to change the bake-time choice. | Set `NEMOCLAW_MINIMAL_BOOTSTRAP=1` before `$$nemoclaw onboard` to skip default template seeding for new/pristine workspaces. **Does not delete files already present.** Partial mitigation for #2598 (cuts ~3k tokens of project-context overhead off OpenClaw's per-turn bootstrap injection). | | Web search backend (Brave, Tavily, and so on) | Runtime through `web.backend` config flag; rebuild only if `web.fetchEnabled` flips | `$$nemoclaw config set --key web.backend --value tavily` | | Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation**. No runtime change | Re-onboard with `$$nemoclaw onboard --recreate-sandbox` | @@ -66,7 +66,7 @@ The host registry caches metadata, but the image and Hermes runtime read from th -## See Also +## Related Topics The table above consolidates details from these topic pages: diff --git a/docs/manage-sandboxes/workspace-files.mdx b/docs/manage-sandboxes/workspace-files.mdx index 81682365f1a..7ed1d3b9fb4 100644 --- a/docs/manage-sandboxes/workspace-files.mdx +++ b/docs/manage-sandboxes/workspace-files.mdx @@ -92,7 +92,7 @@ NemoClaw removes workspace files from the sandbox unless you created a snapshot Back up your workspace files before running `$$nemoclaw destroy`. -See [Backup and Restore](backup-restore) for instructions. +Refer to [Backup and Restore](backup-restore) for instructions. ## Editing Workspace Files diff --git a/docs/monitoring/monitor-sandbox-activity.mdx b/docs/monitoring/monitor-sandbox-activity.mdx index cd4bbe46281..e7db15fcb6d 100644 --- a/docs/monitoring/monitor-sandbox-activity.mdx +++ b/docs/monitoring/monitor-sandbox-activity.mdx @@ -100,7 +100,7 @@ The TUI shows these signals. - Blocked egress requests awaiting operator approval. - Inference routing status. -See [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests) for details about handling blocked requests. +Refer to [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests) for details about handling blocked requests. ## Test Inference diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx index a1b605209b7..4f88220ad26 100644 --- a/docs/network-policy/customize-network-policy.mdx +++ b/docs/network-policy/customize-network-policy.mdx @@ -22,7 +22,7 @@ NemoClaw supports both static policy changes that persist across restarts and dy If the sandbox needs to reach an HTTP service running on the host, expose the service on a host IP that the OpenShell gateway can reach. Apply a custom NemoClaw preset with `$$nemoclaw policy-add --from-file`. Do not rely on `host.docker.internal` as a general host-service path because it bypasses the OpenShell policy path and may not be reachable in every sandbox runtime. -See [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#agent-cannot-reach-a-host-side-http-service). +Refer to [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#agent-cannot-reach-a-host-side-http-service). @@ -183,7 +183,7 @@ Use this flow to test a destination before you decide whether it belongs in a pe NemoClaw ships preset policy files for common integrations in `nemoclaw-blueprint/policies/presets/`. Apply a preset as-is or use it as a starting template for a custom policy. -For guided post-install examples, see [Common Integration Policy Examples](integration-policy-examples). +For guided post-install examples, refer to [Common Integration Policy Examples](integration-policy-examples). During onboarding, the [policy tier](../reference/network-policies#policy-tiers) you select determines which presets are enabled by default. You can add or remove individual presets in the interactive preset screen that follows tier selection. @@ -251,7 +251,7 @@ $$nemoclaw my-assistant policy-remove pypi --yes ``` Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` to drive the same flow from an environment variable. -See [Commands](../reference/commands#$$nemoclaw-name-policy-add) for the full flag reference. +Refer to [Commands](../reference/commands#$$nemoclaw-name-policy-add) for the full flag reference. `$$nemoclaw rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index 1c319f477c0..29afb67daca 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -15,7 +15,7 @@ import { AgentOnly } from "../_components/AgentGuide"; Use these examples when a sandbox is already installed and an integration needs network access. This page covers only integrations that NemoClaw currently ships as maintained policy preset YAML under `nemoclaw-blueprint/policies/presets/`. -For complete blueprint examples that combine a model, agent harness, OpenShell policy, and integration workflow, see [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community). +For complete blueprint examples that combine a model, agent harness, OpenShell policy, and integration workflow, refer to [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community). Integration setup usually has two separate parts: - Configure the integration itself, such as a bot token, OAuth credential, or agent plugin setting. diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index 1c7d23c429a..dc5c200ff38 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -244,7 +244,7 @@ Refer to [Inference Options](../inference/inference-options) for provider config Provider credentials live in the OpenShell gateway store, not on the host filesystem. NemoClaw never writes them to host disk. The OpenShell L7 proxy injects values at egress. -See [Credential Storage](../security/credential-storage) for the inspection, rotation, and migration flow. +Refer to [Credential Storage](../security/credential-storage) for the inspection, rotation, and migration flow. ## Host-Side State and Config diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 4edadc2ac46..fafc3f4ff0b 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -16,7 +16,7 @@ The `nemohermes` alias is the primary interface for managing Hermes sandboxes th It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`). Most commands in this reference use the same arguments and subcommands across agent variants. Use `nemohermes` when you want Hermes selected by default. -For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). +For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). ## Agent Selection @@ -136,7 +136,8 @@ To perform those steps manually, run `nemohermes backup-all`, retire the old gat 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](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. +Credentials are registered with the OpenShell gateway and never persisted to host disk. +Refer to [Credential Storage](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. The legacy `nemohermes setup` command is deprecated; use `nemohermes onboard` instead. After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference. @@ -150,7 +151,7 @@ Three tiers are available: | 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#policy-tiers). +For details on tiers and the presets each includes, refer to [Network Policies](network-policies#policy-tiers). When you finish the policy step, NemoClaw records the finalized built-in preset selection for that sandbox. Later re-onboard runs seed from that finalized selection, so presets you intentionally removed stay removed unless you select them again or override the policy mode. @@ -494,7 +495,7 @@ nemohermes my-assistant config get --key model --format yaml Manage the sandbox config lockdown posture from the host. Use `shields status` to inspect the current state, `shields up` to lock the sandbox config and restore the captured restrictive policy, and `shields down` to temporarily unlock the config for maintenance. -For the full mutability matrix, see [Runtime Controls](../manage-sandboxes/runtime-controls). +For the full mutability matrix, refer to [Runtime Controls](../manage-sandboxes/runtime-controls). ```bash nemohermes my-assistant shields status @@ -692,7 +693,7 @@ For Ollama-backed sandboxes, `destroy` also asks Ollama to unload currently load This command permanently deletes the sandbox **and its persistent volume**. All [workspace files](../manage-sandboxes/workspace-files) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. -Back up your workspace first with `nemohermes snapshot create` or see [Backup and Restore](../manage-sandboxes/backup-restore). +Back up your workspace first with `nemohermes snapshot create` or refer to [Backup and Restore](../manage-sandboxes/backup-restore). If you want to upgrade the sandbox while preserving state, use `nemohermes rebuild` instead. @@ -1652,7 +1653,7 @@ To avoid uninstall destroying host-side user data, uninstall preserves the follo | Entry | What it holds | |---|---| | `rebuild-backups/` | Host-side snapshots that `nemohermes snapshot create` and `nemohermes backup-all` write. `nemohermes snapshot restore` reads them back after you reinstall. | -| `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes (see [Backup and Restore](../manage-sandboxes/backup-restore)). | +| `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes. Refer to [Backup and Restore](../manage-sandboxes/backup-restore). | | `sandboxes.json` | Host-side sandbox registry. NemoClaw uses it to map sandbox names back to their persistence directories when you reinstall. | Uninstall removes every other entry under `~/.nemoclaw/` (gateway source, runtime state, the Ollama auth proxy PID file, etc.). @@ -1697,7 +1698,7 @@ implementation details. They exist to back `install.sh`, `uninstall.sh`, and related automation, and they may change or be removed without notice. Most run indirectly through those scripts rather than being typed by hand. -For contributor guidance on how these command files are structured, see +For contributor guidance on how these command files are structured, refer to `src/commands/internal/README.md`. | Command | Owning script context | Purpose | @@ -1783,7 +1784,7 @@ Set them before running `nemohermes onboard`. | `NEMOCLAW_PREFERRED_API` | `completions` (currently the only honored value) | Forces the validation probe to use the `/v1/chat/completions` API path instead of the newer `/v1/responses` API. | | `NEMOCLAW_INFERENCE_INPUTS` | comma-separated list of `text` and/or `image` | Declares model input modalities for vision-capable models. Validated strictly; unknown tokens are ignored. | | `NEMOCLAW_OLLAMA_REQUIRE_TOOLS` | `0` to disable, anything else to keep the default | When set to `0`, skips the Ollama tool-calling capability check during local-inference onboarding. | -| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location; see the Linux Ollama install mode details below. | +| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location. Refer to the Linux Ollama install mode details below. | | `NEMOCLAW_PROXY_HOST` | hostname or IP | Overrides the sandbox-side outbound HTTP proxy host. Defaults to `10.200.0.1`. | | `NEMOCLAW_PROXY_PORT` | integer port | Overrides the sandbox-side outbound HTTP proxy port. Defaults to `3128`. | | `NEMOCLAW_OPENCLAW_OTEL` | `1` to enable | Enables OpenClaw conversation diagnostics export through the `diagnostics-otel` plugin. Disabled by default. | @@ -1798,7 +1799,7 @@ Set them before running `nemohermes onboard`. | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `deepseek-v4-flash`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. | | `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` | JSON array of non-blank strings | Appends advanced operator-owned tokens to the managed `vllm serve` command after NemoClaw's registry defaults. Example: `["--max-num-seqs","2"]`. Malformed JSON, non-string tokens, or blank tokens fail before Docker work starts. | -| `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see [Runtime Controls](../manage-sandboxes/runtime-controls). | +| `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; refer to [Runtime Controls](../manage-sandboxes/runtime-controls). | | `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). | Hermes-specific provider authentication: @@ -1810,7 +1811,7 @@ Hermes-specific provider authentication: | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | | `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | | `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | -| `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. See [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. | +| `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. Refer to [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. | #### Extra placeholder keys diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index e64636e6f3e..bf2d3668ba8 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -15,7 +15,7 @@ import { AgentOnly } from "../_components/AgentGuide"; The `$$nemoclaw` CLI is the primary interface for managing NemoClaw sandboxes. It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`). -For guidance on when to use `$$nemoclaw` versus the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). +For guidance on when to use `$$nemoclaw` versus the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). @@ -24,7 +24,7 @@ The `nemohermes` alias is the primary interface for managing Hermes sandboxes th It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`). Most commands in this reference use the same arguments and subcommands across agent variants. Use `nemohermes` when you want Hermes selected by default. -For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). +For guidance on choosing between the agent CLIs and the underlying `openshell` CLI, refer to [CLI Selection Guide](cli-selection-guide). @@ -177,7 +177,8 @@ To perform those steps manually, run `$$nemoclaw backup-all`, retire the old gat 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](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. +Credentials are registered with the OpenShell gateway and never persisted to host disk. +Refer to [Credential Storage](../security/credential-storage) for details on inspection, rotation, and migration from earlier releases. The legacy `$$nemoclaw setup` command is deprecated; use `$$nemoclaw onboard` instead. After provider selection, the wizard reviews the provider, model, credential state, and sandbox name before registering inference. @@ -191,7 +192,7 @@ Three tiers are available: | 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#policy-tiers). +For details on tiers and the presets each includes, refer to [Network Policies](network-policies#policy-tiers). When you finish the policy step, NemoClaw records the finalized built-in preset selection for that sandbox. Later re-onboard runs seed from that finalized selection, so presets you intentionally removed stay removed unless you select them again or override the policy mode. @@ -286,7 +287,7 @@ The `$$nemoclaw onboard --help` output lists installed runtime names inline, and Use `--agents ` to declare secondary OpenClaw agents, `agents.defaults`, and main-agent overrides in a checked-in manifest that NemoClaw bakes into the sandbox image at build time. -See [Declarative Multi-Agent Manifest](../inference/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics. +Refer to [Declarative Multi-Agent Manifest](../inference/declarative-agents-manifest) for the schema and OpenClaw-native sub-agent field semantics. @@ -644,7 +645,7 @@ $$nemoclaw my-assistant config get --key model --format yaml Manage the sandbox config lockdown posture from the host. Use `shields status` to inspect the current state, `shields up` to lock the sandbox config and restore the captured restrictive policy, and `shields down` to temporarily unlock the config for maintenance. -For the full mutability matrix, see [Runtime Controls](../manage-sandboxes/runtime-controls). +For the full mutability matrix, refer to [Runtime Controls](../manage-sandboxes/runtime-controls). ```bash $$nemoclaw my-assistant shields status @@ -964,7 +965,7 @@ For Ollama-backed sandboxes, `destroy` also asks Ollama to unload currently load This command permanently deletes the sandbox **and its persistent volume**. All [workspace files](../manage-sandboxes/workspace-files) (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. -Back up your workspace first with `$$nemoclaw snapshot create` or see [Backup and Restore](../manage-sandboxes/backup-restore). +Back up your workspace first with `$$nemoclaw snapshot create` or refer to [Backup and Restore](../manage-sandboxes/backup-restore). If you want to upgrade the sandbox while preserving state, use `$$nemoclaw rebuild` instead. @@ -1276,7 +1277,8 @@ Skill names must contain only alphanumeric characters, dots, hyphens, and unders -OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). +OpenClaw plugins are a different kind of extension. +To install an OpenClaw plugin, refer to [Install OpenClaw Plugins](../manage-sandboxes/install-openclaw-plugins). For OpenClaw, the command uploads the skill to the OpenClaw state directory and mirrors it into `$HOME/.openclaw/skills/` when the agent home directory differs from the state directory. That mirror makes skills listed by `openclaw skills list` available at session startup. If mirror creation fails, NemoClaw prints a warning so you can reinstall or inspect the home directory permissions. @@ -2006,7 +2008,7 @@ To avoid uninstall destroying host-side user data, uninstall preserves the follo | Entry | What it holds | |---|---| | `rebuild-backups/` | Host-side snapshots that `$$nemoclaw snapshot create` and `$$nemoclaw backup-all` write. `$$nemoclaw snapshot restore` reads them back after you reinstall. | -| `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes (see [Backup and Restore](../manage-sandboxes/backup-restore)). | +| `backups/` | Host-side workspace backups that `scripts/backup-workspace.sh` writes. Refer to [Backup and Restore](../manage-sandboxes/backup-restore). | | `sandboxes.json` | Host-side sandbox registry. NemoClaw uses it to map sandbox names back to their persistence directories when you reinstall. | Uninstall removes every other entry under `~/.nemoclaw/` (gateway source, runtime state, the Ollama auth proxy PID file, etc.). @@ -2051,7 +2053,7 @@ implementation details. They exist to back `install.sh`, `uninstall.sh`, and related automation, and they may change or be removed without notice. Most run indirectly through those scripts rather than being typed by hand. -For contributor guidance on how these command files are structured, see +For contributor guidance on how these command files are structured, refer to `src/commands/internal/README.md`. | Command | Owning script context | Purpose | @@ -2152,7 +2154,7 @@ Set them before running `$$nemoclaw onboard`. | `NEMOCLAW_PREFERRED_API` | `completions` (currently the only honored value) | Forces the validation probe to use the `/v1/chat/completions` API path instead of the newer `/v1/responses` API. | | `NEMOCLAW_INFERENCE_INPUTS` | comma-separated list of `text` and/or `image` | Declares model input modalities for vision-capable models. Validated strictly; unknown tokens are ignored. | | `NEMOCLAW_OLLAMA_REQUIRE_TOOLS` | `0` to disable, anything else to keep the default | When set to `0`, skips the Ollama tool-calling capability check during local-inference onboarding. | -| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location; see the Linux Ollama install mode details below. | +| `NEMOCLAW_OLLAMA_INSTALL_MODE` | `system`, `user`, or empty/unset | Pins the Linux Ollama install location. Refer to the Linux Ollama install mode details below. | | `NEMOCLAW_PROXY_HOST` | hostname or IP | Overrides the sandbox-side outbound HTTP proxy host. Defaults to `10.200.0.1`. | | `NEMOCLAW_PROXY_PORT` | integer port | Overrides the sandbox-side outbound HTTP proxy port. Defaults to `3128`. | | `NEMOCLAW_OPENCLAW_OTEL` | `1` to enable | Enables OpenClaw conversation diagnostics export through the `diagnostics-otel` plugin. Disabled by default. | @@ -2167,7 +2169,7 @@ Set them before running `$$nemoclaw onboard`. | `NEMOCLAW_INSTALL_TAG` | release tag | For internal installer commands: the release tag to install. Defaults to the admin-promoted `lkg` tag when unset. Overridden by the `--install-tag` flag. | | `NEMOCLAW_VLLM_MODEL` | registry slug or Hugging Face model id | Selects the model the managed-vLLM install path serves. Recognised slugs: `qwen3.6-27b`, `qwen3.6-35b-a3b-nvfp4`, `nemotron-3-nano-4b`, `deepseek-v4-flash`, `deepseek-r1-distill-70b`. Unset uses the per-platform profile default. Gated models (e.g. `deepseek-r1-distill-70b`) require `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`. | | `NEMOCLAW_VLLM_EXTRA_ARGS_JSON` | JSON array of non-blank strings | Appends advanced operator-owned tokens to the managed `vllm serve` command after NemoClaw's registry defaults. Example: `["--max-num-seqs","2"]`. Malformed JSON, non-string tokens, or blank tokens fail before Docker work starts. | -| `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; see [Runtime Controls](../manage-sandboxes/runtime-controls). | +| `NEMOCLAW_MINIMAL_BOOTSTRAP` | `1` to enable | Skips default OpenClaw workspace-template seeding for new pristine workspaces. Existing files are not deleted; refer to [Runtime Controls](../manage-sandboxes/runtime-controls). | | `NEMOCLAW_MODEL_ROUTER_PYTHON` | absolute path | Pins the host Python interpreter used to create the Model Router virtual environment. Strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to another python. Relative command names such as `python3.12` are rejected. When unset, NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, retains every interpreter whose version is in `[3.10, 3.14)` and whose `ensurepip`, `pyexpat`, `ssl`, and `venv` stdlib modules import cleanly, and tries `python -m venv` on each in priority order until one succeeds. Set the pin when the auto-discovered interpreter is broken (for example, Homebrew `python@3.14` with a `pyexpat` dlopen mismatch on macOS). | @@ -2181,7 +2183,7 @@ OpenClaw-specific build-time agent configuration: | `NEMOCLAW_MAX_TOKENS` | positive integer (tokens) | Overrides the model's `maxTokens` in the built OpenClaw config. | | `NEMOCLAW_REASONING` | `true` or `false` | Overrides the model's reasoning-mode flag in the built OpenClaw config. | | `NEMOCLAW_AGENT_HEARTBEAT_EVERY` | duration with `s`, `m`, or `h` suffix (for example `30m`, `1h`, or `0m`) | Overrides `agents.defaults.heartbeat.every` in the built OpenClaw config. Set `0m` to disable periodic agent turns. | -| `NEMOCLAW_EXTRA_AGENTS_JSON` | JSON array of OpenClaw secondary-agent entries | Adds secondary agents to `agents.list`; see [Extra OpenClaw agents](#extra-openclaw-agents) for the entry schema, path constraints, and validation rules. | +| `NEMOCLAW_EXTRA_AGENTS_JSON` | JSON array of OpenClaw secondary-agent entries | Adds secondary agents to `agents.list`. Refer to [Extra OpenClaw agents](#extra-openclaw-agents) for the entry schema, path constraints, and validation rules. | @@ -2195,7 +2197,7 @@ Hermes-specific provider authentication: | `NEMOCLAW_NOUS_AUTH_METHOD` | same as `NEMOCLAW_HERMES_AUTH_METHOD` | Nous-specific alias for Hermes Provider authentication selection. | | `NEMOCLAW_HERMES_TOOL_GATEWAYS` | comma-separated list | Selects managed Hermes tool gateways in non-interactive onboarding. Valid values are `nous-web`, `nous-image`, `nous-audio`, `nous-browser`, and `nous-code`; the `nous-` prefix is optional. Unknown values fail before sandbox creation. | | `NEMOCLAW_HERMES_TOOL_GATEWAY_PRESETS` | comma-separated list | Back-compatible alias for `NEMOCLAW_HERMES_TOOL_GATEWAYS`. | -| `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. See [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. | +| `NEMOCLAW_EXTRA_PLACEHOLDER_KEYS` | whitespace- or comma-separated list of upper-snake env keys | Adds operator-supplied OpenShell provider rows so per-profile credentials such as `TELEGRAM_BOT_TOKEN_AGENT_A` flow through the same out-of-process placeholder injection that the canonical channel tokens use, instead of being baked into each Hermes profile `.env` as raw text. Refer to [Extra placeholder keys](#extra-placeholder-keys) for the entry shape and validation rules. | @@ -2414,7 +2416,7 @@ The following flags change defaults for commands that manage existing sandboxes. The following variables seed defaults for `$$nemoclaw deploy` and `$$nemoclaw onboard --remote`, which provision a sandbox on a Brev instance. Each has a flag equivalent on `deploy`; the env var lets non-interactive runs skip the prompt. -For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, see [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu). +For narrative how-to coverage of `NEMOCLAW_BREV_PROVIDER` and `NEMOCLAW_GPU`, refer to [Deploy to Remote GPU](../deployment/deploy-to-remote-gpu). | Variable | Default | Effect | |----------|---------|--------| diff --git a/docs/reference/enterprise-readiness.mdx b/docs/reference/enterprise-readiness.mdx index 28d01153cd4..f12760ebc57 100644 --- a/docs/reference/enterprise-readiness.mdx +++ b/docs/reference/enterprise-readiness.mdx @@ -66,19 +66,19 @@ Each row links to deeper documentation and, when a concrete fix is in progress, | Capability area | Status | Notes, workaround, and tracked work | |---|---|---| -| Deny-by-default egress and operator approval | Supported | The sandbox blocks all unlisted outbound traffic and surfaces blocked requests for approval in `openshell term`. Approvals persist within a sandbox instance and reset to the baseline when you destroy and recreate it. See [Approve or Deny Network Requests](../network-policy/approve-network-requests). | -| Network policy configuration | Supported | Edit baseline policy in the blueprint, apply presets, or add endpoints to a running sandbox with `$$nemoclaw policy-add --from-file`. See [Customize the Network Policy](../network-policy/customize-network-policy) and [Network Policies](network-policies). | +| Deny-by-default egress and operator approval | Supported | The sandbox blocks all unlisted outbound traffic and surfaces blocked requests for approval in `openshell term`. Approvals persist within a sandbox instance and reset to the baseline when you destroy and recreate it. Refer to [Approve or Deny Network Requests](../network-policy/approve-network-requests). | +| Network policy configuration | Supported | Edit baseline policy in the blueprint, apply presets, or add endpoints to a running sandbox with `$$nemoclaw policy-add --from-file`. Refer to [Customize the Network Policy](../network-policy/customize-network-policy) and [Network Policies](network-policies). | | Network policy and denial visibility | Supported with caveats | Live activity appears in `openshell term`; lifecycle and gateway output appear in `$$nemoclaw logs`. Denial log readability is being improved in [#4760](https://github.com/NVIDIA/NemoClaw/issues/4760). Default-policy gaps for plugin installs are tracked in [#4104](https://github.com/NVIDIA/NemoClaw/issues/4104) and [#4015](https://github.com/NVIDIA/NemoClaw/issues/4015), and a `policy-add` YAML defect in [#991](https://github.com/NVIDIA/NemoClaw/issues/991). | -| Model and provider switching | Supported | Switch the active provider or model with the NemoClaw inference commands. Some changes rebuild the sandbox image. See [Switch Inference Providers](../inference/switch-inference-providers) and [Inference Options](../inference/inference-options). | +| Model and provider switching | Supported | Switch the active provider or model with the NemoClaw inference commands. Some changes rebuild the sandbox image. Refer to [Switch Inference Providers](../inference/switch-inference-providers) and [Inference Options](../inference/inference-options). | | Multi-agent and multi-sandbox usage | Supported with caveats | Side-by-side sandboxes run on distinct names and dashboard ports, and each name maps to exactly one agent type. Known multi-instance issues include gateway-port collisions ([#5359](https://github.com/NVIDIA/NemoClaw/issues/5359)) and parallel inference routing fallback ([#5343](https://github.com/NVIDIA/NemoClaw/issues/5343)). A declarative multi-agent manifest is roadmap ([#2853](https://github.com/NVIDIA/NemoClaw/issues/2853)). | -| Monitoring and health | Supported | Use `$$nemoclaw status`, `$$nemoclaw logs --follow`, and `openshell term`. See [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity). | +| Monitoring and health | Supported | Use `$$nemoclaw status`, `$$nemoclaw logs --follow`, and `openshell term`. Refer to [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity). | | External telemetry and observability export | Roadmap-only | NemoClaw has no built-in metrics or trace export to external observability backends. An observability adapter plugin is tracked in [#3915](https://github.com/NVIDIA/NemoClaw/issues/3915). OpenShell emits structured platform logs (platform-owned). | -| Audit and session records | Supported with caveats | OpenClaw stores per-session JSONL event logs you can export for audit or compliance review; Hermes stores its own runtime state. Export is manual per sandbox. See [Inspect Agent Session State](../monitoring/monitor-sandbox-activity#inspect-agent-session-state). | -| Resource quotas | Supported with caveats | The entrypoint applies best-effort process and file-descriptor limits (`ulimit -u 512`, `ulimit -n 65536`). Set hard limits through the container runtime for fail-closed enforcement. See [Process Controls](../security/best-practices#process-controls). | +| Audit and session records | Supported with caveats | OpenClaw stores per-session JSONL event logs you can export for audit or compliance review; Hermes stores its own runtime state. Export is manual per sandbox. Refer to [Inspect Agent Session State](../monitoring/monitor-sandbox-activity#inspect-agent-session-state). | +| Resource quotas | Supported with caveats | The entrypoint applies best-effort process and file-descriptor limits (`ulimit -u 512`, `ulimit -n 65536`). Set hard limits through the container runtime for fail-closed enforcement. Refer to [Process Controls](../security/best-practices#process-controls). | | Cost and spend controls | Platform or partner-owned | Deny-by-default egress and routed inference reduce exfiltration and stray endpoints, but NemoClaw does not enforce per-token spend budgets. Set spend limits with your inference provider and monitor unattended agents. | -| Credential isolation | Supported | Inference credentials stay on the host and never enter the sandbox; the agent reaches models through `inference.local`. CLI output redaction adds defense in depth, and OpenClaw sandboxes also run a memory secret scanner. See [Credential Storage](../security/credential-storage) and [Security Best Practices](../security/best-practices). | +| Credential isolation | Supported | Inference credentials stay on the host and never enter the sandbox; the agent reaches models through `inference.local`. CLI output redaction adds defense in depth, and OpenClaw sandboxes also run a memory secret scanner. Refer to [Credential Storage](../security/credential-storage) and [Security Best Practices](../security/best-practices). | | Upgrades and lifecycle | Supported with caveats | Upgrade NemoClaw, then run `$$nemoclaw rebuild` to recreate the sandbox with the current image while backing up and restoring state. Do not run `openclaw update` inside the sandbox; the agent is image-pinned. Known gaps include config restore after rebuild ([#5202](https://github.com/NVIDIA/NemoClaw/issues/5202)) and version attachment flexibility ([#2217](https://github.com/NVIDIA/NemoClaw/issues/2217)). | -| Backup and restore | Supported | Create snapshots and restore workspace and agent state with the snapshot and backup commands. See [Back Up and Restore](../manage-sandboxes/backup-restore). | +| Backup and restore | Supported | Create snapshots and restore workspace and agent state with the snapshot and backup commands. Refer to [Back Up and Restore](../manage-sandboxes/backup-restore). | | Remote and cloud deployment | Supported with caveats | Provision the host, run the installer, and run `$$nemoclaw onboard`; the `$$nemoclaw deploy` Brev wrapper is deprecated. Remote dashboard origins can disable device pairing, so avoid exposing them on shared networks. Brev rough edges are tracked in [#3959](https://github.com/NVIDIA/NemoClaw/issues/3959) and [#3365](https://github.com/NVIDIA/NemoClaw/issues/3365). | @@ -103,7 +103,7 @@ The following table classifies each admin and control-plane expectation by curre | Multi-tenant isolation | Out of scope | Isolation is per-sandbox at the container level. NemoClaw does not provide tenant separation for multiple untrusted users on one host. | | Centralized audit export and SIEM integration | Manual or admin-only | Export per-session JSONL logs by hand for audit review. External telemetry forwarding is roadmap ([#3915](https://github.com/NVIDIA/NemoClaw/issues/3915)). | | Usage quotas, cost budgets, and billing | Platform or partner-owned | Set token and rate limits with your inference provider. NemoClaw does not meter or cap spend. | -| Credential and secrets management | Supported with caveats | Provider credentials live on the host with restricted permissions and redaction. Integration with an external secrets manager is manual. See [Credential Storage](../security/credential-storage). | +| Credential and secrets management | Supported with caveats | Provider credentials live on the host with restricted permissions and redaction. Integration with an external secrets manager is manual. Refer to [Credential Storage](../security/credential-storage). | | Policy as code distributed across a fleet | Manual or admin-only | Baseline policy and presets are versioned in the blueprint and applied per sandbox. There is no fleet-wide policy distribution service. | | High availability and horizontal gateway scaling | Platform or partner-owned | The NemoClaw reference flow targets a single host. Gateway scaling and availability are OpenShell concerns. | | Disaster recovery across a fleet | Manual or admin-only | Per-sandbox snapshot, backup, and restore are supported. Fleet-level disaster recovery is an operator responsibility. | @@ -115,12 +115,12 @@ Each one includes the current workaround or next step. | Limitation | Impact | Workaround or next step | |---|---|---| -| Approved endpoints reset on sandbox recreation | One-off approvals do not survive a destroy and recreate. | Add durable endpoints to the baseline policy or a preset rather than relying on repeated approvals. See [Customize the Network Policy](../network-policy/customize-network-policy). | -| Controls bypassed outside the managed gateway path | Network policy and inference auth are not enforced if a runtime starts outside the NemoClaw-managed entrypoint. | Use NemoClaw-managed onboarding and sandbox entrypoints for production workflows. See [Known Limitations](../security/best-practices#known-limitations). | -| One consumer per messaging bot token | Two sandboxes sharing a bot token disconnect each other and drop messages. | Use a distinct bot token per sandbox. See the messaging troubleshooting in [Troubleshooting](troubleshooting#messaging-bridge-appears-running-but-no-messages-arrive). | -| In-sandbox config edits do not persist | Direct edits to agent config inside the running sandbox do not survive rebuilds. | Make durable config changes from the host by re-running `$$nemoclaw onboard`, not inside the sandbox. See [Troubleshooting](troubleshooting). | -| Landlock filesystem enforcement degrades on old kernels | Filesystem restrictions fall back to container mounts below Linux kernel 5.13. | Run on kernel 5.13 or later for full enforcement. See [Landlock LSM Enforcement](../security/best-practices#landlock-lsm-enforcement). | -| Best-effort capability and resource limits | Capability drops and ulimits skip silently when the runtime blocks them. | Pass `--cap-drop=ALL` and `--ulimit` at the container runtime, or set `NEMOCLAW_REQUIRE_CAP_DROP=1` to fail closed. See [Process Controls](../security/best-practices#process-controls). | +| Approved endpoints reset on sandbox recreation | One-off approvals do not survive a destroy and recreate. | Add durable endpoints to the baseline policy or a preset rather than relying on repeated approvals. Refer to [Customize the Network Policy](../network-policy/customize-network-policy). | +| Controls bypassed outside the managed gateway path | Network policy and inference auth are not enforced if a runtime starts outside the NemoClaw-managed entrypoint. | Use NemoClaw-managed onboarding and sandbox entrypoints for production workflows. Refer to [Known Limitations](../security/best-practices#known-limitations). | +| One consumer per messaging bot token | Two sandboxes sharing a bot token disconnect each other and drop messages. | Use a distinct bot token per sandbox. Refer to the messaging troubleshooting in [Troubleshooting](troubleshooting#messaging-bridge-appears-running-but-no-messages-arrive). | +| In-sandbox config edits do not persist | Direct edits to agent config inside the running sandbox do not survive rebuilds. | Make durable config changes from the host by re-running `$$nemoclaw onboard`, not inside the sandbox. Refer to [Troubleshooting](troubleshooting). | +| Landlock filesystem enforcement degrades on old kernels | Filesystem restrictions fall back to container mounts below Linux kernel 5.13. | Run on kernel 5.13 or later for full enforcement. Refer to [Landlock LSM Enforcement](../security/best-practices#landlock-lsm-enforcement). | +| Best-effort capability and resource limits | Capability drops and ulimits skip silently when the runtime blocks them. | Pass `--cap-drop=ALL` and `--ulimit` at the container runtime, or set `NEMOCLAW_REQUIRE_CAP_DROP=1` to fail closed. Refer to [Process Controls](../security/best-practices#process-controls). | ## Field Conversation Guidance diff --git a/docs/reference/network-policies.mdx b/docs/reference/network-policies.mdx index 85ef0ad10ca..be50051430a 100644 --- a/docs/reference/network-policies.mdx +++ b/docs/reference/network-policies.mdx @@ -52,7 +52,7 @@ All endpoints use TLS termination and are enforced at port 443. GitHub access (`github.com`, `api.github.com`) is not included in the baseline policy. Apply the `github` preset during onboarding if your agent needs GitHub access. -See [Customize the Network Policy](../network-policy/customize-network-policy). +Refer to [Customize the Network Policy](../network-policy/customize-network-policy). The baseline policy does not include messaging endpoints for Telegram, Discord, Slack, WeChat, or WhatsApp. Enable the channel during onboarding or apply the matching messaging preset so the sandbox can reach that platform. diff --git a/docs/reference/platform-support.mdx b/docs/reference/platform-support.mdx index 636755ae825..048e33f52c9 100644 --- a/docs/reference/platform-support.mdx +++ b/docs/reference/platform-support.mdx @@ -30,7 +30,7 @@ Update the JSON so the tables and partial views on other pages stay in sync with ## Project Status -For version highlights, see [Release Notes](../about/release-notes). +For version highlights, refer to [Release Notes](../about/release-notes). {/* project-status:begin */} - **Stage:** alpha @@ -73,7 +73,7 @@ Pick the matching onboarding entry point for each agent. The table below lists every platform tracked by NemoClaw, including deferred entries that are on the roadmap but not yet validated. The `CI` column reports whether the platform has a dedicated GitHub Actions job. A "Tested with limitations" row that is not in CI carries a stronger caveat than one that is. -For the onboarding-time supported set without deferred rows, see [Prerequisites](../get-started/prerequisites#platforms). +For the onboarding-time supported set without deferred rows, refer to [Prerequisites](../get-started/prerequisites#platforms). {/* platform-matrix-full:begin */} | OS | Container runtime | Status | PRD priority | CI | Notes | @@ -176,7 +176,7 @@ They are listed here so launch material, sales conversations, and support triage ## Known Caveats and Active Blockers -- Sandbox bounding-set capability drop on hosts without `CAP_SETPCAP` is partially fixed. The agent process tree drops dangerous caps with `NEMOCLAW_REQUIRE_CAP_DROP=1` (see [#4707](https://github.com/NVIDIA/NemoClaw/pull/4707)). The `nemoclaw connect` shell still inherits the container's create-time bounding set on Colossus, Docker Desktop, and WSL hosts where `CAP_SETPCAP` is absent. The remaining fix is upstream in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452). See tracking [#3280](https://github.com/NVIDIA/NemoClaw/issues/3280). +- Sandbox bounding-set capability drop on hosts without `CAP_SETPCAP` is partially fixed. The agent process tree drops dangerous caps with `NEMOCLAW_REQUIRE_CAP_DROP=1` (refer to [#4707](https://github.com/NVIDIA/NemoClaw/pull/4707)). The `nemoclaw connect` shell still inherits the container's create-time bounding set on Colossus, Docker Desktop, and WSL hosts where `CAP_SETPCAP` is absent. The remaining fix is upstream in [NVIDIA/OpenShell#1452](https://github.com/NVIDIA/OpenShell/issues/1452). Refer to tracking [#3280](https://github.com/NVIDIA/NemoClaw/issues/3280). ## Using This Matrix diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index 0e0d1c57561..e1fee6917e4 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -253,7 +253,7 @@ NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0 NEMOCLAW_GATEWAY_PORT=8990 $$nemoclaw onbo Use `NEMOCLAW_GATEWAY_BIND_ADDRESS=0.0.0.0` only when other hosts on the network should be able to reach the gateway. -See [Environment Variables](commands#environment-variables) for the full list of port overrides. +Refer to [Environment Variables](commands#environment-variables) for the full list of port overrides. ### Running multiple sandboxes simultaneously @@ -738,7 +738,7 @@ If Ollama times out during a cold model load, NemoClaw retries once with a 300-s If all attempts fail, the error includes container reachability diagnostics such as HTTP status and host gateway resolution. `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only covers the inference-server validation probe. -The post-create readiness wait has its own budget (`NEMOCLAW_SANDBOX_READY_TIMEOUT`); see [Sandbox onboard times out with "did not become ready within Ns"](#sandbox-onboard-times-out-with-did-not-become-ready-within-ns) for the readiness path. +The post-create readiness wait has its own budget (`NEMOCLAW_SANDBOX_READY_TIMEOUT`); refer to [Sandbox onboard times out with "did not become ready within Ns"](#sandbox-onboard-times-out-with-did-not-become-ready-within-ns) for the readiness path. ### Sandbox onboard times out with "did not become ready within Ns" @@ -1173,7 +1173,7 @@ Current versions derive the dashboard port from `CHAT_UI_URL` automatically and CHAT_UI_URL=http://127.0.0.1:19000 $$nemoclaw onboard ``` -If you need to run multiple sandboxes at different ports at the same time, see [Running multiple sandboxes simultaneously](#running-multiple-sandboxes-simultaneously). +If you need to run multiple sandboxes at different ports at the same time, refer to [Running multiple sandboxes simultaneously](#running-multiple-sandboxes-simultaneously). ### Control UI config endpoint returns 404 or non-JSON @@ -1299,7 +1299,7 @@ http://host.openshell.internal:11435/v1 `11435` there and forwards requests to `127.0.0.1:11434` on the host. If you need a different host service exposed to the sandbox, route it through the OpenShell gateway rather than relying on `host.docker.internal`. -See issue [#3136](https://github.com/NVIDIA/NemoClaw/issues/3136). +Refer to issue [#3136](https://github.com/NVIDIA/NemoClaw/issues/3136). ### Local inference health check resolves to IPv6 @@ -1440,7 +1440,7 @@ If you run other services on Spark that expect port 3000, bind them to a differe ## Windows Subsystem for Linux -For environment setup steps, see [Windows Prerequisites](../get-started/prerequisites/windows-preparation). +For environment setup steps, refer to [Windows Prerequisites](../get-started/prerequisites/windows-preparation). ### `wsl --install --no-distribution` returns Forbidden (403) @@ -1516,12 +1516,12 @@ sudo systemctl stop ollama OLLAMA_CONTEXT_LENGTH=16384 ollama serve ``` -For additional troubleshooting, see the [Windows Setup](../get-started/prerequisites/windows-preparation) page. +For additional troubleshooting, refer to the [Windows Setup](../get-started/prerequisites/windows-preparation) page. -For first-time OpenClaw setup, see the [Quickstart](../get-started/quickstart). +For first-time OpenClaw setup, refer to the [Quickstart](../get-started/quickstart). -For first-time Hermes setup, see [Quickstart with Hermes](../get-started/quickstart). +For first-time Hermes setup, refer to [Quickstart with Hermes](../get-started/quickstart). ## Podman @@ -1734,7 +1734,7 @@ Reset a specific provider's credentials with `nemohermes credentials reset OpenShell enforces the platform-level mechanisms that NemoClaw configures, including network namespace isolation, seccomp filters, SSRF protection, TLS termination, and gateway authentication. -For the full platform-level controls reference, see [OpenShell Security Best Practices](https://docs.nvidia.com/openshell/latest/security/best-practices.html). +For the full platform-level controls reference, refer to [OpenShell Security Best Practices](https://docs.nvidia.com/openshell/latest/security/best-practices.html). */} @@ -93,10 +93,10 @@ flowchart TB ## Network Controls NemoClaw controls which hosts, ports, and HTTP methods the sandbox can reach, and lets you approve or deny requests in real time. -Network policy allowlists do not disable OpenShell's SSRF guard; see [Customize the Network Policy](/network-policy/customize-network-policy) for the interaction between egress rules and internal-address blocking. +Network policy allowlists do not disable OpenShell's SSRF guard; refer to [Customize the Network Policy](/network-policy/customize-network-policy) for the interaction between egress rules and internal-address blocking. {/* OpenShell provides additional network enforcement mechanisms not covered here, including network namespace isolation, SSRF protection, TLS auto-detection and termination, and audit-vs-enforce modes. -See the [Network Controls](https://docs.nvidia.com/openshell/latest/security/best-practices.html#network-controls) section of the OpenShell Security Best Practices. */} +Refer to the [Network Controls](https://docs.nvidia.com/openshell/latest/security/best-practices.html#network-controls) section of the OpenShell Security Best Practices. */} ### Deny-by-Default Egress @@ -185,7 +185,7 @@ Review the preset's YAML file before applying to understand the endpoints, metho NemoClaw restricts which paths the agent can read and write, protecting system binaries, configuration files, and gateway credentials. {/* OpenShell covers additional filesystem enforcement details, including `hard_requirement` compatibility mode for Landlock and policy path validation rules. -See the [Filesystem Controls](https://docs.nvidia.com/openshell/latest/security/best-practices.html#filesystem-controls) section of the OpenShell Security Best Practices. */} +Refer to the [Filesystem Controls](https://docs.nvidia.com/openshell/latest/security/best-practices.html#filesystem-controls) section of the OpenShell Security Best Practices. */} ### Read-Only System Paths @@ -293,7 +293,7 @@ Landlock is a Linux Security Module that enforces filesystem access rules at the NemoClaw limits the capabilities, user privileges, and resource quotas available to processes inside the sandbox. {/* OpenShell enforces additional process-level controls not covered here, including seccomp BPF socket domain filters and a specific enforcement application order (namespace entry, privilege drop, Landlock, seccomp). -See the [Process Controls](https://docs.nvidia.com/openshell/latest/security/best-practices.html#process-controls) section of the OpenShell Security Best Practices. */} +Refer to the [Process Controls](https://docs.nvidia.com/openshell/latest/security/best-practices.html#process-controls) section of the OpenShell Security Best Practices. */} ### Capability Drops diff --git a/docs/security/credential-storage.mdx b/docs/security/credential-storage.mdx index 200ac46f9a0..9a6fc43ffba 100644 --- a/docs/security/credential-storage.mdx +++ b/docs/security/credential-storage.mdx @@ -136,4 +136,4 @@ On the next run NemoClaw prompts again unless the credential is supplied through ## Related Files -For the broader sandbox security model and operational trade-offs, see [Security Best Practices](best-practices) and [Architecture](../reference/architecture). +For the broader sandbox security model and operational trade-offs, refer to [Security Best Practices](best-practices) and [Architecture](../reference/architecture).