From 2204aaba747d181acffa927447186562768881ee Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Mon, 1 Jun 2026 13:14:38 -0700 Subject: [PATCH 01/12] docs: multi-layer doc per agent --- docs/_components/AgentGuide.tsx | 60 +++++ docs/about/ecosystem-hermes.mdx | 102 +++++++ docs/about/ecosystem.mdx | 2 +- docs/about/how-it-works.mdx | 52 +++- docs/about/overview.mdx | 26 +- docs/index.mdx | 43 +-- docs/index.yml | 464 ++++++++++++++++++++++---------- fern/docs.yml | 92 ++++++- 8 files changed, 651 insertions(+), 190 deletions(-) create mode 100644 docs/_components/AgentGuide.tsx create mode 100644 docs/about/ecosystem-hermes.mdx diff --git a/docs/_components/AgentGuide.tsx b/docs/_components/AgentGuide.tsx new file mode 100644 index 0000000000..82d7e32395 --- /dev/null +++ b/docs/_components/AgentGuide.tsx @@ -0,0 +1,60 @@ +/* + * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * Resolves OpenClaw vs Hermes user-guide variant from the URL path. + * Use for CLI names, quickstart links, and explore cards on shared MDX pages. + */ +declare const React: unknown; + +export type GuideVariant = "openclaw" | "hermes"; + +const HERMES_PATH = "/user-guide/hermes/"; + +export function getGuideVariant(): GuideVariant { + if (typeof window !== "undefined" && window.location.pathname.includes(HERMES_PATH)) { + return "hermes"; + } + return "openclaw"; +} + +/** Full site path for the active guide variant (includes /user-guide/{variant}). */ +export function guidePath(suffix: string): string { + const normalized = suffix.startsWith("/") ? suffix : `/${suffix}`; + return `/user-guide/${getGuideVariant()}${normalized}`; +} + +export function AgentCli() { + return {getGuideVariant() === "hermes" ? "nemohermes" : "nemoclaw"}; +} + +export function AgentProductName() { + return <>{getGuideVariant() === "hermes" ? "NemoHermes" : "NemoClaw"}; +} + +export function AgentOnly({ + variant, + children, +}: { + variant: GuideVariant; + children: unknown; +}) { + if (getGuideVariant() !== variant) { + return null; + } + return <>{children}; +} + +export function GuideLink({ + href, + children, +}: { + href: string; + children: unknown; +}) { + const resolved = + href.startsWith("http://") || href.startsWith("https://") ? href : guidePath(href); + return {children}; +} diff --git a/docs/about/ecosystem-hermes.mdx b/docs/about/ecosystem-hermes.mdx new file mode 100644 index 0000000000..7f360084db --- /dev/null +++ b/docs/about/ecosystem-hermes.mdx @@ -0,0 +1,102 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Ecosystem" +sidebar-title: "Ecosystem" +description: "How Hermes, OpenShell, and NemoClaw form one stack, where NemoClaw sits, what it adds beyond a DIY OpenShell deployment, and when to use the reference integration versus OpenShell alone." +description-agent: "Explains how Hermes, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond integrating OpenShell yourself, and when to prefer NemoHermes versus OpenShell. Use when users ask about Hermes, OpenShell, and NemoClaw together, or when to use NemoClaw versus OpenShell for Hermes." +keywords: ["nemoclaw ecosystem", "hermes agent", "nemohermes", "nemoclaw vs openshell", "run hermes openshell sandbox"] +content: + type: "concept" +--- +NemoClaw provides onboarding, lifecycle management, and Hermes operations within OpenShell containers. +Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected. + +This page describes how the ecosystem is formed across projects, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and how to choose between NemoHermes and OpenShell alone. + +## How the Stack Fits Together + +There are three pieces in a NemoClaw for Hermes deployment: Hermes, OpenShell, and NemoClaw, each with a distinct scope. +The following diagram shows how they fit together. + +```mermaid +flowchart TB + NC["🦞 NVIDIA NemoClaw
CLI, blueprint"] + OS["🐚 NVIDIA OpenShell
Gateway, policy, inference routing"] + HM["Hermes
Agent in sandbox"] + + NC -->|orchestrates| OS + OS -->|isolates and runs| HM + + classDef nv fill:#76b900,stroke:#333,color:#fff + classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a + classDef nvDark fill:#333,stroke:#76b900,color:#fff + + class NC nv + class OS nv + class HM nvDark + + linkStyle 0 stroke:#76b900,stroke-width:2px + linkStyle 1 stroke:#76b900,stroke-width:2px +``` + +NemoClaw sits above OpenShell in the operator workflow. +It drives OpenShell APIs and CLI to create and configure the sandbox that runs Hermes. +Models and endpoints sit behind OpenShell's inference routing. +NemoClaw onboarding wires provider choice into that routing, including the Hermes Provider route when you onboard through `nemohermes`. + +The following table shows the scope of each component in the stack. + +| Project | Scope | +|---------|--------| +| [Hermes](https://hermes-agent.nousresearch.com/docs/) | The agent: runtime, tools, messaging adapters, and an OpenAI-compatible API inside the container. It does not define the sandbox or the host gateway. | +| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | +| NemoClaw | The NVIDIA reference stack on the host: `nemohermes` / `nemoclaw` CLI, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so Hermes runs inside OpenShell in a documented, repeatable way. | + +## NemoClaw Path versus OpenShell Path + +Both paths assume OpenShell can sandbox a workload. +The difference is who owns the integration work. + +| Path | What it means | +|------|---------------| +| **NemoClaw path** | You adopt the reference stack. NemoClaw's Hermes blueprint encodes a hardened image, default policies, and orchestration so `nemohermes onboard` can stand up a known-good Hermes-on-OpenShell setup with less custom glue. | +| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | + +## What NemoClaw Adds Beyond DIY OpenShell + +You can run Hermes inside OpenShell without NemoClaw by building your own image, writing policy YAML, registering providers, and wiring inference routes yourself. +That path is valid when you need full control over the container layout. + +NemoClaw builds on OpenShell with additional security hardening, automation, and lifecycle tooling for Hermes. +The following table compares DIY OpenShell integration with `nemohermes onboard`. + +| Capability | DIY OpenShell + Hermes | `nemohermes onboard` | +|---|---|---| +| Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. | +| Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. | +| Image hardening | Depends on your base image and install steps. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | +| Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. | +| Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates credentials from the host, configures the OpenShell route, and bakes model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. | +| Channel messaging | OpenShell delivers channel tokens through its provider system and L7 proxy; you configure Hermes platform adapters manually. | NemoClaw automates supported channel setup during onboarding and bakes Hermes env/config with placeholder tokens that OpenShell resolves at egress. | +| Blueprint versioning | No NemoClaw blueprint; your image tag is whatever you built locally. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemohermes onboard` on different machines produces the same sandbox. | +| State migration | Not included unless you build it. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. | +| Process count limits | You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint on top of OpenShell's seccomp and privilege dropping. | + +## When to Use Which + +Use the following table to decide when to use NemoHermes versus OpenShell alone. + +| Situation | Prefer | +|-----------|--------| +| You want Hermes with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw (`nemohermes`) | +| You need maximum flexibility for custom images, a layout that does not match the NemoClaw Hermes blueprint, or a workload outside this reference stack. | OpenShell with your own integration | +| You are standardizing on the NVIDIA reference for always-on Hermes agents with policy and inference routing. | NemoClaw (`nemohermes`) | +| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | + +## Related topics + +- [Overview](/about/overview) contains what NemoClaw is, capabilities, benefits, and use cases. +- [How It Works](/about/how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes. +- [Architecture](/reference/architecture) shows the repository structure and technical diagrams. +- [Quickstart with Hermes](/get-started/quickstart-hermes) installs NemoClaw and launches your first Hermes sandbox. diff --git a/docs/about/ecosystem.mdx b/docs/about/ecosystem.mdx index 36c11f2153..52da89f26f 100644 --- a/docs/about/ecosystem.mdx +++ b/docs/about/ecosystem.mdx @@ -15,7 +15,7 @@ This page describes how the ecosystem is formed across projects, where NemoClaw ## How the Stack Fits Together -There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope. +There are three pieces that are put together in a NemoClaw for OpenClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope. The following diagram shows how they fit together. ```mermaid diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index b992f15eff..1ff47bef73 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -9,10 +9,18 @@ keywords: ["how nemoclaw works", "nemoclaw sandbox lifecycle blueprint"] content: type: "concept" --- +import { AgentCli, AgentOnly, GuideLink } 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, plugin configuration, and state helpers. +It packages them into a repeatable setup with a host CLI, a versioned blueprint, default policies, inference setup, and state helpers. + +OpenClaw sandboxes also load the NemoClaw plugin for managed inference metadata and the `/nemoclaw` slash command. + + +Hermes sandboxes receive agent configuration under `/sandbox/.hermes` during onboarding instead of the OpenClaw plugin path. + You can use that setup directly or adapt it for your own OpenShell integration. ## High-Level Flow @@ -30,7 +38,7 @@ The diagram has the following components: | Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. | | NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. | | OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. | -| NemoClaw sandbox | Runs the onboarded agent with the selected blueprint contents and supporting tools. OpenClaw sandboxes also load the NemoClaw plugin. | +| NemoClaw sandbox | Runs the onboarded agent with the selected blueprint contents and supporting tools. | | Inference | Receives model requests through the gateway, using NVIDIA endpoints, NIM, or compatible APIs. | | Integrations | Reach messaging services, MCP servers, GitHub, package indexes, or model hubs through gateway-managed egress. | | State and artifacts | Store configuration, credentials, logs, workspace files, policies, and transcripts outside the running agent process. | @@ -41,17 +49,18 @@ For repository layout, file paths, and deeper diagrams, see [Architecture](/refe NemoClaw architecture follows the following principles. -Thin plugin, versioned blueprint -: The sandbox plugin stays small and stable. Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. +Versioned blueprint +: Host-side orchestration uses a versioned blueprint and runner that can evolve on its own release cadence. + The OpenClaw sandbox plugin stays small and stable inside the container. Respect CLI boundaries -: The `nemoclaw` CLI is the primary interface for sandbox management. +: The CLI is the primary interface for sandbox management. Supply chain safety : Blueprint artifacts are immutable, versioned, and digest-verified before execution. OpenShell-backed lifecycle -: NemoClaw orchestrates OpenShell resources under the hood, but `nemoclaw onboard` +: NemoClaw orchestrates OpenShell resources under the hood, but onboard is the supported operator entry point for creating or recreating NemoClaw-managed sandboxes. Reproducible setup @@ -59,19 +68,28 @@ Reproducible setup ## CLI, Plugin, and Blueprint -NemoClaw is split into three integration pieces: +NemoClaw is split into integration pieces on the host and in the sandbox image: - The _host CLI_ runs onboarding, validates provider choices, stores configuration, and calls OpenShell commands for gateway, provider, sandbox, and policy operations. + + - The _plugin_ is a TypeScript package that runs with OpenClaw inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. + + + + +- _Hermes runtime configuration_ is written into `/sandbox/.hermes` during onboarding, including `config.yaml`, environment files, and platform adapter settings for supported messaging channels. + + - The _blueprint_ is a versioned YAML package with the sandbox image, policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell. -This separation keeps the sandbox plugin small while allowing host orchestration and blueprint contents to evolve on their own release cadence. +This separation keeps agent-specific sandbox assets focused while allowing host orchestration and blueprint contents to evolve on their own release cadence. ## Sandbox Creation -When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs your selected agent in an isolated container. +When you run onboard, NemoClaw creates an OpenShell sandbox that runs your selected agent in an isolated container. The host CLI and blueprint runner orchestrate this process through the OpenShell CLI: 1. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest. @@ -87,6 +105,9 @@ OpenShell intercepts every inference call and routes it to the configured provid During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell route, and bakes the matching model reference into the sandbox image. The sandbox then talks to `inference.local`, while the host owns the actual provider credential and upstream endpoint. If you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. + +For Hermes, runtime model switches through inference set update `/sandbox/.hermes/config.yaml` without rebuilding the sandbox. + ## Protection Layers @@ -105,7 +126,16 @@ For details on the baseline rules, refer to [Network Policies](/reference/networ ## Next Steps -- Read [Ecosystem](/about/ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths. -- Follow the [Quickstart with OpenClaw](/get-started/quickstart) or [Quickstart with Hermes](/get-started/quickstart-hermes) to launch your first sandbox. +- Read Ecosystem for stack-level relationships and NemoClaw versus OpenShell-only paths. + + +- Follow the Quickstart with OpenClaw to launch your first sandbox. + + + + +- Follow the Quickstart with Hermes 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. diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 5e22e2fdcb..85e490a7c4 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -11,6 +11,8 @@ content: skill: priority: 10 --- +import { AgentCli, AgentOnly, GuideLink } 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. @@ -18,7 +20,7 @@ This enables self-evolving agents to run more safely in clouds, on prem, RTX PCs NemoClaw pairs hosted models on inference providers or local endpoints with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). -NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run supported agents there. +NemoClaw adds the blueprint, CLI, onboarding, and related tooling as the reference way to run supported agents there. | Capability | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -51,7 +53,7 @@ NemoClaw provides the following benefits to mitigate these risks. | Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | | Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Inference Options](/inference/inference-options). | | Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | -| Single CLI | The `nemoclaw` command orchestrates the full stack: gateway, sandbox, inference provider, and network policy. | +| 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 @@ -68,9 +70,17 @@ You can use NemoClaw for various use cases including the following. Navigate to the following topics to learn more about NemoClaw and how to install and use it. -- [Architecture Overview](/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. -- [Quickstart with OpenClaw](/get-started/quickstart) to install NemoClaw and run your first OpenClaw sandbox. -- [Quickstart with Hermes](/get-started/quickstart-hermes) to install NemoClaw and run a Hermes sandbox. -- [Agent Skills](/resources/agent-skills) to load NemoClaw guidance into an AI coding assistant. -- [Inference Options](/inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. +- Architecture Overview to understand how NemoClaw works. +- Ecosystem to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. + + +- Quickstart with OpenClaw to install NemoClaw and run your first OpenClaw sandbox. + + + + +- Quickstart with Hermes to install NemoClaw and run your first Hermes sandbox with `nemohermes`. + + +- Agent Skills to load NemoClaw guidance into an AI coding assistant. +- Inference Options to check the inference providers that NemoClaw supports and how inference routing works. diff --git a/docs/index.mdx b/docs/index.mdx index 7d5f6d8f31..f2b6807b97 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -2,12 +2,14 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "NVIDIA NemoClaw" -sidebar-title: "NVIDIA NemoClaw Developer Guide" +sidebar-title: "Home" description: "NemoClaw is an open-source reference stack for running sandboxed AI agents more safely, with a single command and packaged agent skills." keywords: "NemoClaw, OpenClaw, Hermes, OpenShell, AI agents, agent skills, sandboxing, inference routing" +layout: overview position: 1 --- +import { AgentOnly, guidePath } from "./_components/AgentGuide"; import { BadgeLinks } from "./_components/BadgeLinks"; import { CommandTerminal } from "./_components/CommandTerminal"; @@ -56,8 +58,8 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash | Agent | Guide | |-------|-------| -| OpenClaw (default) | [Quickstart with OpenClaw](/get-started/quickstart) | -| Hermes | [Quickstart with Hermes](/get-started/quickstart-hermes) | +| OpenClaw (default) | [Quickstart with OpenClaw](/user-guide/openclaw/get-started/quickstart) | +| Hermes | [Quickstart with Hermes](/user-guide/hermes/get-started/quickstart-hermes) | ## Use NemoClaw User Skills @@ -66,7 +68,7 @@ The skills turn these docs into task-focused guidance that your assistant can ap - + Clone the skills or add them to your assistant so NemoClaw guidance is available directly in chat. @@ -82,98 +84,99 @@ Clone the skills or add them to your assistant so NemoClaw guidance is available
- + Learn what NemoClaw is, what capabilities it provides, and when to use it. Concept - + -Understand the host CLI, plugin, blueprint, sandbox lifecycle, and protection layers. +Understand the host CLI, blueprint, sandbox lifecycle, and protection layers. Concept - + -Learn how OpenClaw, OpenShell, and NemoClaw fit together. +Learn how OpenClaw, OpenShell, and NemoClaw fit together. +Learn how Hermes, OpenShell, and NemoClaw fit together. Concept - + Track NemoClaw release changes and component version policy. Reference - + Install NemoClaw, verify prerequisites, and run your first sandboxed agent. Guide - + Use NemoClaw's packaged agent skills to guide coding assistants through common workflows. Resource - + Choose how NemoClaw routes model requests and configures inference providers. Guide - + Create, inspect, update, and clean up NemoClaw sandboxes. Guide - + Approve, deny, and customize sandbox network access. Guide - + Deploy NemoClaw to remote GPU instances and manage deployment-specific setup. Guide - + Inspect sandbox health, logs, and agent behavior during runtime. Guide - + Review sandbox controls, credential handling, and security trade-offs. Guide - + Look up architecture details, CLI commands, policies, and troubleshooting guidance. Reference - + Learn about the NemoClaw architecture, plugin structure, and blueprint design in detail. diff --git a/docs/index.yml b/docs/index.yml index 4925942034..4d87db8833 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -1,150 +1,324 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -landing-page: - page: "Home" - path: index.mdx +tabs: + user-guide: + display-name: User Guide + icon: book-open navigation: - - section: "About NemoClaw" - slug: about - contents: - - page: "Overview" - path: about/overview.mdx - slug: overview - - page: "Architecture Overview" - path: about/how-it-works.mdx - slug: how-it-works - - page: "Ecosystem" - path: about/ecosystem.mdx - slug: ecosystem - - page: "Release Notes" - path: about/release-notes.mdx - slug: release-notes - - section: "Get Started" - slug: get-started - contents: - - section: "Prerequisites" - path: get-started/prerequisites.mdx - slug: prerequisites - contents: - - page: "(Windows Only) Windows Prerequisites" - path: get-started/windows-preparation.mdx - slug: windows-preparation - - page: "Quickstart with OpenClaw" - path: get-started/quickstart.mdx - slug: quickstart - - page: "Quickstart with Hermes" - path: get-started/quickstart-hermes.mdx - slug: quickstart-hermes - - section: "Inference" - slug: inference - contents: - - page: "Inference Options" - path: inference/inference-options.mdx - slug: inference-options - - page: "Use Local Inference" - path: inference/use-local-inference.mdx - slug: use-local-inference - - page: "Tool-Calling Reliability" - path: inference/tool-calling-reliability.mdx - slug: tool-calling-reliability - - page: "Switch Inference Providers" - path: inference/switch-inference-providers.mdx - slug: switch-inference-providers - - page: "Set Up Task-Specific Sub-Agents" - path: inference/set-up-sub-agent.mdx - - section: "Manage Sandboxes" - slug: manage-sandboxes - contents: - - page: "Manage Sandbox Lifecycle" - path: manage-sandboxes/lifecycle.mdx - slug: lifecycle - - page: "Runtime Controls" - path: manage-sandboxes/runtime-controls.mdx - slug: runtime-controls - - page: "Set Up Messaging Channels" - path: manage-sandboxes/messaging-channels.mdx - slug: messaging-channels - - page: "Workspace Files" - path: manage-sandboxes/workspace-files.mdx - slug: workspace-files - - page: "Backup and Restore" - path: manage-sandboxes/backup-restore.mdx - slug: backup-restore - - section: "Network Policy" - slug: network-policy - contents: - - page: "Approve or Deny Network Requests" - path: network-policy/approve-network-requests.mdx - slug: approve-network-requests - - page: "Customize the Network Policy" - path: network-policy/customize-network-policy.mdx - slug: customize-network-policy - - page: "Integration Policy Examples" - path: network-policy/integration-policy-examples.mdx - slug: integration-policy-examples - - section: "Deployment" - slug: deployment - contents: - - page: "Deploy to Remote GPU Instances" - path: deployment/deploy-to-remote-gpu.mdx - slug: deploy-to-remote-gpu - - page: "Brev Web UI" - path: deployment/brev-web-ui.mdx - slug: brev-web-ui - - page: "Install OpenClaw Plugins" - path: deployment/install-openclaw-plugins.mdx - slug: install-openclaw-plugins - - page: "Sandbox Hardening" - path: deployment/sandbox-hardening.mdx - slug: sandbox-hardening - - section: "Monitoring" - slug: monitoring - contents: - - page: "Monitor Sandbox Activity" - path: monitoring/monitor-sandbox-activity.mdx - slug: monitor-sandbox-activity - - section: "Security" - slug: security - contents: - - page: "Security Best Practices" - path: security/best-practices.mdx - slug: best-practices - - page: "Credential Storage" - path: security/credential-storage.mdx - slug: credential-storage - - page: "OpenClaw Controls" - path: security/openclaw-controls.mdx - slug: openclaw-controls - - section: "Reference" - slug: reference - contents: - - page: "Architecture Details" - path: reference/architecture.mdx - slug: architecture - - page: "CLI Commands Reference" - path: reference/commands.mdx - slug: commands - - page: "CLI Selection Guide" - path: reference/cli-selection-guide.mdx - slug: cli-selection-guide - - page: "Network Policies" - path: reference/network-policies.mdx - slug: network-policies - - page: "Troubleshooting" - path: reference/troubleshooting.mdx - slug: troubleshooting - - section: "Resources" - slug: resources - contents: - - page: "Agent Skills" - path: resources/agent-skills.mdx - slug: agent-skills - - link: "Report Vulnerabilities" - href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md - - page: "License" - path: resources/license.mdx - slug: license - - link: "Discord" - href: https://discord.gg/XFpfPv9Uvx + - tab: user-guide + variants: + - title: NemoClaw for OpenClaw + subtitle: Guide for the OpenClaw agent + slug: openclaw + default: true + layout: + - page: "Home" + path: index.mdx + slug: home + - section: "About NemoClaw" + slug: about + collapsed: open-by-default + contents: + - page: "Overview" + path: about/overview.mdx + slug: overview + - page: "Architecture Overview" + path: about/how-it-works.mdx + slug: how-it-works + - page: "Ecosystem" + path: about/ecosystem.mdx + slug: ecosystem + - page: "Release Notes" + path: about/release-notes.mdx + slug: release-notes + - section: "Get Started" + slug: get-started + collapsed: open-by-default + contents: + - section: "Prerequisites" + path: get-started/prerequisites.mdx + slug: prerequisites + contents: + - page: "(Windows Only) Windows Prerequisites" + path: get-started/windows-preparation.mdx + slug: windows-preparation + - page: "Quickstart with OpenClaw" + path: get-started/quickstart.mdx + slug: quickstart + - section: "Inference" + slug: inference + collapsed: open-by-default + contents: + - page: "Inference Options" + path: inference/inference-options.mdx + slug: inference-options + - page: "Use Local Inference" + path: inference/use-local-inference.mdx + slug: use-local-inference + - page: "Tool-Calling Reliability" + path: inference/tool-calling-reliability.mdx + slug: tool-calling-reliability + - page: "Switch Inference Providers" + path: inference/switch-inference-providers.mdx + slug: switch-inference-providers + - page: "Set Up Task-Specific Sub-Agents" + path: inference/set-up-sub-agent.mdx + - section: "Manage Sandboxes" + slug: manage-sandboxes + collapsed: open-by-default + contents: + - page: "Manage Sandbox Lifecycle" + path: manage-sandboxes/lifecycle.mdx + slug: lifecycle + - page: "Runtime Controls" + path: manage-sandboxes/runtime-controls.mdx + slug: runtime-controls + - page: "Set Up Messaging Channels" + path: manage-sandboxes/messaging-channels.mdx + slug: messaging-channels + - page: "Workspace Files" + path: manage-sandboxes/workspace-files.mdx + slug: workspace-files + - page: "Backup and Restore" + path: manage-sandboxes/backup-restore.mdx + slug: backup-restore + - section: "Network Policy" + slug: network-policy + collapsed: open-by-default + contents: + - page: "Approve or Deny Network Requests" + path: network-policy/approve-network-requests.mdx + slug: approve-network-requests + - page: "Customize the Network Policy" + path: network-policy/customize-network-policy.mdx + slug: customize-network-policy + - page: "Integration Policy Examples" + path: network-policy/integration-policy-examples.mdx + slug: integration-policy-examples + - section: "Deployment" + slug: deployment + collapsed: open-by-default + contents: + - page: "Deploy to Remote GPU Instances" + path: deployment/deploy-to-remote-gpu.mdx + slug: deploy-to-remote-gpu + - page: "Brev Web UI" + path: deployment/brev-web-ui.mdx + slug: brev-web-ui + - page: "Install OpenClaw Plugins" + path: deployment/install-openclaw-plugins.mdx + slug: install-openclaw-plugins + - page: "Sandbox Hardening" + path: deployment/sandbox-hardening.mdx + slug: sandbox-hardening + - section: "Monitoring" + slug: monitoring + collapsed: open-by-default + contents: + - page: "Monitor Sandbox Activity" + path: monitoring/monitor-sandbox-activity.mdx + slug: monitor-sandbox-activity + - section: "Security" + slug: security + collapsed: open-by-default + contents: + - page: "Security Best Practices" + path: security/best-practices.mdx + slug: best-practices + - page: "Credential Storage" + path: security/credential-storage.mdx + slug: credential-storage + - page: "OpenClaw Controls" + path: security/openclaw-controls.mdx + slug: openclaw-controls + - section: "Reference" + slug: reference + collapsed: open-by-default + contents: + - page: "Architecture Details" + path: reference/architecture.mdx + slug: architecture + - page: "CLI Commands Reference" + path: reference/commands.mdx + slug: commands + - page: "CLI Selection Guide" + path: reference/cli-selection-guide.mdx + slug: cli-selection-guide + - page: "Network Policies" + path: reference/network-policies.mdx + slug: network-policies + - page: "Troubleshooting" + path: reference/troubleshooting.mdx + slug: troubleshooting + - section: "Resources" + slug: resources + collapsed: open-by-default + contents: + - page: "Agent Skills" + path: resources/agent-skills.mdx + slug: agent-skills + - link: "Report Vulnerabilities" + href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md + - page: "License" + path: resources/license.mdx + slug: license + - link: "Discord" + href: https://discord.gg/XFpfPv9Uvx + - title: NemoClaw for Hermes + subtitle: Guide for the Hermes agent + slug: hermes + layout: + - page: "Home" + path: index.mdx + slug: home + - section: "About NemoClaw" + slug: about + collapsed: open-by-default + contents: + - page: "Overview" + path: about/overview.mdx + slug: overview + - page: "Architecture Overview" + path: about/how-it-works.mdx + slug: how-it-works + - page: "Ecosystem" + path: about/ecosystem-hermes.mdx + slug: ecosystem + - page: "Release Notes" + path: about/release-notes.mdx + slug: release-notes + - section: "Get Started" + slug: get-started + collapsed: open-by-default + contents: + - section: "Prerequisites" + path: get-started/prerequisites.mdx + slug: prerequisites + contents: + - page: "(Windows Only) Windows Prerequisites" + path: get-started/windows-preparation.mdx + slug: windows-preparation + - page: "Quickstart with Hermes" + path: get-started/quickstart-hermes.mdx + slug: quickstart-hermes + - section: "Inference" + slug: inference + collapsed: open-by-default + contents: + - page: "Inference Options" + path: inference/inference-options.mdx + slug: inference-options + - page: "Use Local Inference" + path: inference/use-local-inference.mdx + slug: use-local-inference + - page: "Tool-Calling Reliability" + path: inference/tool-calling-reliability.mdx + slug: tool-calling-reliability + - page: "Switch Inference Providers" + path: inference/switch-inference-providers.mdx + slug: switch-inference-providers + - page: "Set Up Task-Specific Sub-Agents" + path: inference/set-up-sub-agent.mdx + - section: "Manage Sandboxes" + slug: manage-sandboxes + collapsed: open-by-default + contents: + - page: "Manage Sandbox Lifecycle" + path: manage-sandboxes/lifecycle.mdx + slug: lifecycle + - page: "Runtime Controls" + path: manage-sandboxes/runtime-controls.mdx + slug: runtime-controls + - page: "Set Up Messaging Channels" + path: manage-sandboxes/messaging-channels.mdx + slug: messaging-channels + - page: "Workspace Files" + path: manage-sandboxes/workspace-files.mdx + slug: workspace-files + - page: "Backup and Restore" + path: manage-sandboxes/backup-restore.mdx + slug: backup-restore + - section: "Network Policy" + slug: network-policy + collapsed: open-by-default + contents: + - page: "Approve or Deny Network Requests" + path: network-policy/approve-network-requests.mdx + slug: approve-network-requests + - page: "Customize the Network Policy" + path: network-policy/customize-network-policy.mdx + slug: customize-network-policy + - page: "Integration Policy Examples" + path: network-policy/integration-policy-examples.mdx + slug: integration-policy-examples + - section: "Deployment" + slug: deployment + collapsed: open-by-default + contents: + - page: "Deploy to Remote GPU Instances" + path: deployment/deploy-to-remote-gpu.mdx + slug: deploy-to-remote-gpu + - page: "Brev Web UI" + path: deployment/brev-web-ui.mdx + slug: brev-web-ui + - page: "Install OpenClaw Plugins" + path: deployment/install-openclaw-plugins.mdx + slug: install-openclaw-plugins + - page: "Sandbox Hardening" + path: deployment/sandbox-hardening.mdx + slug: sandbox-hardening + - section: "Monitoring" + slug: monitoring + collapsed: open-by-default + contents: + - page: "Monitor Sandbox Activity" + path: monitoring/monitor-sandbox-activity.mdx + slug: monitor-sandbox-activity + - section: "Security" + slug: security + collapsed: open-by-default + contents: + - page: "Security Best Practices" + path: security/best-practices.mdx + slug: best-practices + - page: "Credential Storage" + path: security/credential-storage.mdx + slug: credential-storage + - page: "OpenClaw Controls" + path: security/openclaw-controls.mdx + slug: openclaw-controls + - section: "Reference" + slug: reference + collapsed: open-by-default + contents: + - page: "Architecture Details" + path: reference/architecture.mdx + slug: architecture + - page: "CLI Commands Reference" + path: reference/commands.mdx + slug: commands + - page: "CLI Selection Guide" + path: reference/cli-selection-guide.mdx + slug: cli-selection-guide + - page: "Network Policies" + path: reference/network-policies.mdx + slug: network-policies + - page: "Troubleshooting" + path: reference/troubleshooting.mdx + slug: troubleshooting + - section: "Resources" + slug: resources + collapsed: open-by-default + contents: + - page: "Agent Skills" + path: resources/agent-skills.mdx + slug: agent-skills + - link: "Report Vulnerabilities" + href: https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md + - page: "License" + path: resources/license.mdx + slug: license + - link: "Discord" + href: https://discord.gg/XFpfPv9Uvx diff --git a/fern/docs.yml b/fern/docs.yml index 5deb46b226..d46f068250 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -73,6 +73,12 @@ redirects: destination: "/nemoclaw/latest" - source: "/nemoclaw/latest/index" destination: "/nemoclaw/latest" + - source: "/nemoclaw/latest" + destination: "/nemoclaw/latest/user-guide/openclaw/home" + - source: "/nemoclaw/home" + destination: "/nemoclaw/latest/user-guide/openclaw/home" + - source: "/nemoclaw/latest/home" + destination: "/nemoclaw/latest/user-guide/openclaw/home" - source: "/nemoclaw/latest/:path*/index.html" destination: "/nemoclaw/latest/:path*" - source: "/nemoclaw/:path*/index.html" @@ -80,12 +86,88 @@ redirects: - source: "/nemoclaw/:path*.html" destination: "/nemoclaw/:path*" - source: "/nemoclaw/latest/reference/inference-profiles" - destination: "/nemoclaw/latest/inference/inference-options" + destination: "/nemoclaw/latest/user-guide/openclaw/inference/inference-options" - source: "/nemoclaw/latest/get-started/windows-setup" - destination: "/nemoclaw/latest/get-started/windows-preparation" + destination: "/nemoclaw/latest/user-guide/openclaw/get-started/prerequisites/windows-preparation" - source: "/nemoclaw/latest/deployment/set-up-telegram-bridge" - destination: "/nemoclaw/latest/manage-sandboxes/messaging-channels" + destination: "/nemoclaw/latest/user-guide/openclaw/manage-sandboxes/messaging-channels" - source: "/nemoclaw/latest/workspace/workspace-files" - destination: "/nemoclaw/latest/manage-sandboxes/workspace-files" + destination: "/nemoclaw/latest/user-guide/openclaw/manage-sandboxes/workspace-files" - source: "/nemoclaw/latest/workspace/backup-restore" - destination: "/nemoclaw/latest/manage-sandboxes/backup-restore" + destination: "/nemoclaw/latest/user-guide/openclaw/manage-sandboxes/backup-restore" + # Variant titles can differ from URL slugs; redirect auto-derived slugs to stable openclaw/hermes paths. + - source: "/nemoclaw/latest/user-guide/open-claw/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/:path*" + - source: "/nemoclaw/user-guide/open-claw/:path*" + destination: "/nemoclaw/user-guide/openclaw/:path*" + - source: "/nemoclaw/latest/user-guide/nemoclaw-for-openclaw/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/:path*" + - source: "/nemoclaw/latest/user-guide/nemoclaw-for-hermes/:path*" + destination: "/nemoclaw/latest/user-guide/hermes/:path*" + - source: "/nemoclaw/user-guide/nemoclaw-for-openclaw/:path*" + destination: "/nemoclaw/user-guide/openclaw/:path*" + - source: "/nemoclaw/user-guide/nemoclaw-for-hermes/:path*" + destination: "/nemoclaw/user-guide/hermes/:path*" + # User Guide tab with OpenClaw/Hermes variants: preserve legacy flat URLs (OpenClaw default). + - source: "/nemoclaw/latest/about/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/about/:path*" + - source: "/nemoclaw/latest/get-started/quickstart-hermes" + destination: "/nemoclaw/latest/user-guide/hermes/get-started/quickstart-hermes" + - source: "/nemoclaw/latest/get-started/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/get-started/:path*" + - source: "/nemoclaw/latest/inference/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/inference/:path*" + - source: "/nemoclaw/latest/manage-sandboxes/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/manage-sandboxes/:path*" + - source: "/nemoclaw/latest/network-policy/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/network-policy/:path*" + - source: "/nemoclaw/latest/deployment/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/deployment/:path*" + - source: "/nemoclaw/latest/monitoring/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/monitoring/:path*" + - source: "/nemoclaw/latest/security/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/security/:path*" + - source: "/nemoclaw/latest/reference/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/reference/:path*" + - source: "/nemoclaw/latest/resources/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/resources/:path*" + # Prior tab layout redirects → User Guide OpenClaw variant. + - source: "/nemoclaw/latest/guides/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/:path*" + - source: "/nemoclaw/latest/get-started/openclaw/:path*" + destination: "/nemoclaw/latest/user-guide/openclaw/get-started/:path*" + - source: "/nemoclaw/latest/get-started/hermes/quickstart-hermes" + destination: "/nemoclaw/latest/user-guide/hermes/get-started/quickstart-hermes" + - source: "/nemoclaw/latest/get-started/hermes/:path*" + destination: "/nemoclaw/latest/user-guide/hermes/get-started/:path*" + # Same redirects without the version slug (Fern check canonical paths). + - source: "/nemoclaw/about/:path*" + destination: "/nemoclaw/user-guide/openclaw/about/:path*" + - source: "/nemoclaw/get-started/quickstart-hermes" + destination: "/nemoclaw/user-guide/hermes/get-started/quickstart-hermes" + - source: "/nemoclaw/get-started/:path*" + destination: "/nemoclaw/user-guide/openclaw/get-started/:path*" + - source: "/nemoclaw/inference/:path*" + destination: "/nemoclaw/user-guide/openclaw/inference/:path*" + - source: "/nemoclaw/manage-sandboxes/:path*" + destination: "/nemoclaw/user-guide/openclaw/manage-sandboxes/:path*" + - source: "/nemoclaw/network-policy/:path*" + destination: "/nemoclaw/user-guide/openclaw/network-policy/:path*" + - source: "/nemoclaw/deployment/:path*" + destination: "/nemoclaw/user-guide/openclaw/deployment/:path*" + - source: "/nemoclaw/monitoring/:path*" + destination: "/nemoclaw/user-guide/openclaw/monitoring/:path*" + - source: "/nemoclaw/security/:path*" + destination: "/nemoclaw/user-guide/openclaw/security/:path*" + - source: "/nemoclaw/reference/:path*" + destination: "/nemoclaw/user-guide/openclaw/reference/:path*" + - source: "/nemoclaw/resources/:path*" + destination: "/nemoclaw/user-guide/openclaw/resources/:path*" + - source: "/nemoclaw/guides/:path*" + destination: "/nemoclaw/user-guide/openclaw/:path*" + - source: "/nemoclaw/get-started/openclaw/:path*" + destination: "/nemoclaw/user-guide/openclaw/get-started/:path*" + - source: "/nemoclaw/get-started/hermes/quickstart-hermes" + destination: "/nemoclaw/user-guide/hermes/get-started/quickstart-hermes" + - source: "/nemoclaw/get-started/hermes/:path*" + destination: "/nemoclaw/user-guide/hermes/get-started/:path*" From f87c8875a36824b7766ee8fcc9fb4a0e23cf7e97 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Mon, 1 Jun 2026 17:53:16 -0700 Subject: [PATCH 02/12] docs: remaining work for tab-variants per agent --- docs/_components/AgentGuide.tsx | 13 +- docs/about/ecosystem-hermes.mdx | 8 +- docs/about/ecosystem.mdx | 6 +- docs/about/how-it-works.mdx | 19 +- docs/about/overview.mdx | 20 +- docs/about/release-notes.mdx | 36 +-- docs/get-started/prerequisites.mdx | 8 +- docs/get-started/quickstart-hermes.mdx | 14 +- docs/get-started/quickstart.mdx | 30 +- docs/get-started/windows-preparation.mdx | 29 +- docs/index.yml | 30 +- docs/inference/inference-options.mdx | 47 ++- docs/inference/set-up-sub-agent.mdx | 6 +- docs/inference/switch-inference-providers.mdx | 185 +++++++++++- docs/inference/tool-calling-reliability.mdx | 6 +- docs/inference/use-local-inference.mdx | 213 ++++++++++++-- docs/manage-sandboxes/backup-restore.mdx | 127 +++++++- .../install-plugins-hermes.mdx | 14 + docs/manage-sandboxes/lifecycle.mdx | 278 ++++++++++++++++-- docs/manage-sandboxes/messaging-channels.mdx | 176 ++++++++++- docs/manage-sandboxes/runtime-controls.mdx | 55 +++- docs/manage-sandboxes/workspace-files.mdx | 51 +++- docs/monitoring/monitor-sandbox-activity.mdx | 64 +++- .../approve-network-requests.mdx | 8 +- .../customize-network-policy.mdx | 153 ++++++++-- .../integration-policy-examples.mdx | 216 +++++++++++++- docs/reference/architecture.mdx | 4 +- docs/reference/cli-selection-guide.mdx | 14 +- docs/reference/commands.mdx | 14 +- docs/reference/network-policies.mdx | 4 +- docs/reference/troubleshooting.mdx | 18 +- docs/security/best-practices.mdx | 86 ++++-- docs/security/credential-storage.mdx | 61 +++- docs/security/hermes-controls.mdx | 12 + docs/security/openclaw-controls.mdx | 4 +- 35 files changed, 1772 insertions(+), 257 deletions(-) create mode 100644 docs/manage-sandboxes/install-plugins-hermes.mdx create mode 100644 docs/security/hermes-controls.mdx diff --git a/docs/_components/AgentGuide.tsx b/docs/_components/AgentGuide.tsx index 82d7e32395..69023ce30a 100644 --- a/docs/_components/AgentGuide.tsx +++ b/docs/_components/AgentGuide.tsx @@ -11,7 +11,8 @@ declare const React: unknown; export type GuideVariant = "openclaw" | "hermes"; -const HERMES_PATH = "/user-guide/hermes/"; +const GUIDE_PATH = "/user-guide/"; +const HERMES_PATH = `${GUIDE_PATH}hermes`; export function getGuideVariant(): GuideVariant { if (typeof window !== "undefined" && window.location.pathname.includes(HERMES_PATH)) { @@ -20,10 +21,18 @@ export function getGuideVariant(): GuideVariant { return "openclaw"; } +function guideBasePath(): string { + if (typeof window === "undefined") { + return ""; + } + const guideIndex = window.location.pathname.indexOf(GUIDE_PATH); + return guideIndex === -1 ? "" : window.location.pathname.slice(0, guideIndex); +} + /** Full site path for the active guide variant (includes /user-guide/{variant}). */ export function guidePath(suffix: string): string { const normalized = suffix.startsWith("/") ? suffix : `/${suffix}`; - return `/user-guide/${getGuideVariant()}${normalized}`; + return `${guideBasePath()}${GUIDE_PATH}${getGuideVariant()}${normalized}`; } export function AgentCli() { diff --git a/docs/about/ecosystem-hermes.mdx b/docs/about/ecosystem-hermes.mdx index 7f360084db..ec462185c3 100644 --- a/docs/about/ecosystem-hermes.mdx +++ b/docs/about/ecosystem-hermes.mdx @@ -96,7 +96,7 @@ Use the following table to decide when to use NemoHermes versus OpenShell alone. ## Related topics -- [Overview](/about/overview) contains what NemoClaw is, capabilities, benefits, and use cases. -- [How It Works](/about/how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes. -- [Architecture](/reference/architecture) shows the repository structure and technical diagrams. -- [Quickstart with Hermes](/get-started/quickstart-hermes) installs NemoClaw and launches your first Hermes sandbox. +- [Overview](overview) contains what NemoClaw is, capabilities, benefits, and use cases. +- [How It Works](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes. +- [Architecture](../reference/architecture) shows the repository structure and technical diagrams. +- [Quickstart with Hermes](../get-started/quickstart-hermes) installs NemoClaw and launches your first Hermes sandbox. diff --git a/docs/about/ecosystem.mdx b/docs/about/ecosystem.mdx index 52da89f26f..f1ff78d56f 100644 --- a/docs/about/ecosystem.mdx +++ b/docs/about/ecosystem.mdx @@ -96,6 +96,6 @@ Use the following table to decide when to use NemoClaw versus OpenShell. ## Related topics -- [Overview](/about/overview) contains what NemoClaw is, capabilities, benefits, and use cases. -- [How It Works](/about/how-it-works) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers. -- [Architecture](/reference/architecture) shows the repository structure and technical diagrams. +- [Overview](overview) contains what NemoClaw is, capabilities, benefits, and use cases. +- [How It Works](how-it-works) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers. +- [Architecture](../reference/architecture) shows the repository structure and technical diagrams. diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 1ff47bef73..d4bf998752 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -9,7 +9,7 @@ keywords: ["how nemoclaw works", "nemoclaw sandbox lifecycle blueprint"] content: type: "concept" --- -import { AgentCli, AgentOnly, GuideLink } from "../_components/AgentGuide"; +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. @@ -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, see [Architecture](../reference/architecture). ## Design Principles @@ -122,20 +122,23 @@ The sandbox starts with a default policy that controls network egress, filesyste When the agent tries to reach an unlisted host, OpenShell blocks the request and surfaces it in the TUI for operator approval. Approved endpoints persist for the current session but are not saved to the baseline policy file. -For details on the baseline rules, refer to [Network Policies](/reference/network-policies). For container-level hardening, refer to [Sandbox Hardening](/deployment/sandbox-hardening). +For details on the baseline rules, refer to [Network Policies](../reference/network-policies). For container-level hardening, refer to [Sandbox Hardening](../deployment/sandbox-hardening). ## Next Steps -- Read Ecosystem for stack-level relationships and NemoClaw versus OpenShell-only paths. -- Follow the Quickstart with OpenClaw to launch your first sandbox. +- 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. -- Follow the Quickstart with Hermes to launch your first sandbox. +- Read [Ecosystem](ecosystem-hermes) for stack-level relationships and NemoClaw versus OpenShell-only paths. +- Follow [Quickstart with Hermes](../get-started/quickstart-hermes) 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. -- 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. diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 32868800e2..296a85aa67 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -11,7 +11,7 @@ content: skill: priority: 10 --- -import { AgentCli, AgentOnly, GuideLink } from "../_components/AgentGuide"; +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. @@ -51,7 +51,7 @@ NemoClaw provides the following benefits to mitigate these risks. | Benefit | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------| | Sandboxed execution | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. No access is granted by default. | -| Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Inference Options](/inference/inference-options). | +| Routed inference | Model traffic is routed through the OpenShell gateway to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Inference Options](../inference/inference-options). | | Declarative network policy | Egress rules are defined in YAML. Unknown hosts are blocked and surfaced to the operator for approval. | | 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. | @@ -70,17 +70,21 @@ You can use NemoClaw for various use cases including the following. Navigate to the following topics to learn more about NemoClaw and how to install and use it. -- Architecture Overview to understand how NemoClaw works. -- Ecosystem to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. -- Quickstart with OpenClaw to install NemoClaw and run your first OpenClaw sandbox. +- [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. +- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant. +- [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. -- Quickstart with Hermes to install NemoClaw and run your first Hermes sandbox with `nemohermes`. +- [Architecture Overview](how-it-works) to understand how NemoClaw works. +- [Ecosystem](ecosystem-hermes) 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-hermes) to install NemoClaw and run your first Hermes sandbox with `nemohermes`. +- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant. +- [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works. -- Agent Skills to load NemoClaw guidance into an AI coding assistant. -- 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 352989d3e4..33c83c0383 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -15,33 +15,33 @@ NVIDIA NemoClaw is available in early preview starting March 16, 2026. Use this NemoClaw v0.0.56 improves install safety, local-inference validation, messaging diagnostics, sandbox lifecycle reporting, and day-two command behavior: -- Public installer and `nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to [Manage Sandbox Lifecycle](/manage-sandboxes/lifecycle). -- `nemoclaw status`, `nemoclaw connect`, and `nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to [NemoClaw CLI Commands Reference](/reference/commands). -- GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to [Use a Local Inference Server](/inference/use-local-inference). -- Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to [Messaging Channels](/manage-sandboxes/messaging-channels). -- Command ergonomics are clearer for common day-two paths. `nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `nemoclaw status --json` supports per-sandbox automation, and `nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to [NemoClaw CLI Commands Reference](/reference/commands). -- Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to [Common NemoClaw Integration Policy Examples](/network-policy/integration-policy-examples). -- Uninstall, rebuild, and snapshot flows protect user state more consistently. `nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to [Manage Sandbox Lifecycle](/manage-sandboxes/lifecycle). +- Public installer and `nemoclaw update` flows now follow the admin-promoted `lkg` release tag by default, so curl-piped installs and update checks target the maintained build while validation catches up to newer semver tags. Non-interactive Linux installs can also reactivate Docker group membership through `sg docker` and continue in the same installer run when that path is available. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). +- `nemoclaw status`, `nemoclaw connect`, and `nemoclaw upgrade-sandboxes` now probe the live sandbox agent version before deciding whether a rebuild is needed, instead of trusting stale host metadata. Status output reports when the version cannot be verified and points at rebuild when the running agent may predate the current install. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- GPU Docker-driver local-inference onboarding now verifies that host-network sandboxes can reach the selected Ollama or vLLM health endpoint before onboarding reports success. Failures now include the provider endpoint, container network mode, and recovery guidance, which avoids discovering the broken route only after the first agent prompt. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). +- Messaging setup is more diagnosable. Slack setup validates both required Slack credentials before enabling the channel, WhatsApp pairing renders a compact scan-friendly QR for OpenClaw sandboxes and separates gateway close errors from QR rendering, and Telegram DM allowlist aliases continue to work for existing automation. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). +- Command ergonomics are clearer for common day-two paths. `nemoclaw inference set` without both `--provider` and `--model` now points users to the underlying `openshell inference set` command, `nemoclaw skill remove ` removes uploaded skills by `SKILL.md` name, `nemoclaw status --json` supports per-sandbox automation, and `nemoclaw debug --sandbox` validates explicit sandbox names before writing diagnostics. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Policy and sandbox base-image compatibility improved. The `pypi` preset allows the `uv` package manager binary, the sandbox base image includes `tmux` for OpenClaw's bundled tmux-session flow, and Jira preset validation docs now use observable status probes. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). +- Uninstall, rebuild, and snapshot flows protect user state more consistently. `nemoclaw uninstall` preserves host-side backups and the sandbox registry by default, rebuilds preserve explicit CPU-only sandbox intent, and snapshot restore blocks ambiguous existing-destination rollbacks unless you opt in with `--force`. For more information, refer to [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle). ## v0.0.55 NemoClaw v0.0.55 improves local Ollama onboarding reliability, plugin secret-scanner resilience, and messaging-channel prompt clarity: -- Local Ollama validation retries host-side curl process timeouts with a larger timeout before failing, and Docker runtime detection retries `docker info` before choosing the local inference route. For more information, refer to [Use a Local Inference Server](/inference/use-local-inference). -- The NemoClaw OpenClaw plugin keeps the memory secret scanner active when OpenClaw runs in embedded fallback mode without a usable path resolver. The scanner falls back to literal memory and workspace-relative paths instead of crashing before the first write-tool call. For more information, refer to [Security Best Practices](/security/best-practices). -- The onboarding messaging-channel picker now states that pressing Enter with no channels selected skips messaging setup. For more information, refer to [Messaging Channels](/manage-sandboxes/messaging-channels). +- Local Ollama validation retries host-side curl process timeouts with a larger timeout before failing, and Docker runtime detection retries `docker info` before choosing the local inference route. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). +- The NemoClaw OpenClaw plugin keeps the memory secret scanner active when OpenClaw runs in embedded fallback mode without a usable path resolver. The scanner falls back to literal memory and workspace-relative paths instead of crashing before the first write-tool call. For more information, refer to [Security Best Practices](../security/best-practices). +- The onboarding messaging-channel picker now states that pressing Enter with no channels selected skips messaging setup. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). ## v0.0.54 NemoClaw v0.0.54 updates messaging activation, Windows WSL onboarding, NemoHermes dashboard access, and sandbox repair paths: -- Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to [Messaging Channels](/manage-sandboxes/messaging-channels). -- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to [Prepare Windows for NemoClaw](/get-started/windows-preparation). -- Windows-host Ollama setup inside WSL now requires the Docker Desktop WSL integration path. NemoClaw still shows Windows-host Ollama options when it detects them, but labels the Docker Desktop requirement and blocks unsupported native Docker-in-WSL selections before it tries to start or install Ollama. For more information, refer to [Use a Local Inference Server](/inference/use-local-inference). -- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to [NemoClaw Quickstart with Hermes](/get-started/quickstart-hermes). -- Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: ` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to [NemoClaw CLI Commands Reference](/reference/commands). -- Homebrew stays on the Linuxbrew prefix while exposing installed formula commands in sandbox shell sessions, the `/nemoclaw` slash command activates at OpenClaw startup again, Hermes rebuilds tolerate older release tarballs that lack optional UI package lockfiles, and device scope-upgrade approvals recover without being pinned to the old gateway-scoped request. For more information, refer to [Common NemoClaw Integration Policy Examples](/network-policy/integration-policy-examples). -- The host-gateway allowance for OpenClaw `web_fetch` is confined to the trusted proxy path, while strict and direct paths continue to block host-gateway names. Hermes Provider onboarding skips the host-side smoke probe only for OAuth-backed setup and keeps direct validation for Nous API key setup. For more information, refer to [NemoClaw Inference Options](/inference/inference-options). +- Generated OpenClaw config now marks Telegram, Discord, Slack, and WhatsApp as enabled at the channel level. Selected messaging plugins are pinned during the image build, and `channels add` verifies Telegram, Discord, and Slack bridge startup after the rebuild instead of leaving silent channel failures for later debugging. For more information, refer to [Messaging Channels](../manage-sandboxes/messaging-channels). +- The Windows bootstrap flow waits for Ubuntu account creation before touching Docker settings, enables Docker Desktop WSL integration for the target distro, avoids changing the global WSL default distro, and adds WSL-specific Docker reachability hints during onboarding. For more information, refer to [Prepare Windows for NemoClaw](../get-started/windows-preparation). +- Windows-host Ollama setup inside WSL now requires the Docker Desktop WSL integration path. NemoClaw still shows Windows-host Ollama options when it detects them, but labels the Docker Desktop requirement and blocks unsupported native Docker-in-WSL selections before it tries to start or install Ollama. For more information, refer to [Use a Local Inference Server](../inference/use-local-inference). +- NemoHermes can expose the optional native Hermes web dashboard separately from the OpenAI-compatible API. Set `NEMOCLAW_HERMES_DASHBOARD=1` before onboarding to start and forward the dashboard on port `9119`, with `NEMOCLAW_HERMES_DASHBOARD_PORT` and `NEMOCLAW_HERMES_DASHBOARD_TUI` available for port and TUI tab control. For more information, refer to [NemoClaw Quickstart with Hermes](../get-started/quickstart-hermes). +- Onboarding diagnostics include more copy-paste-ready recovery hints. Invalid sandbox names now include a `Try: ` line when NemoClaw can derive a valid name, and non-interactive NVIDIA Endpoints setup prints the exact `export NVIDIA_API_KEY=nvapi-...` shape when the key is missing. For more information, refer to [NemoClaw CLI Commands Reference](../reference/commands). +- Homebrew stays on the Linuxbrew prefix while exposing installed formula commands in sandbox shell sessions, the `/nemoclaw` slash command activates at OpenClaw startup again, Hermes rebuilds tolerate older release tarballs that lack optional UI package lockfiles, and device scope-upgrade approvals recover without being pinned to the old gateway-scoped request. For more information, refer to [Common NemoClaw Integration Policy Examples](../network-policy/integration-policy-examples). +- The host-gateway allowance for OpenClaw `web_fetch` is confined to the trusted proxy path, while strict and direct paths continue to block host-gateway names. Hermes Provider onboarding skips the host-side smoke probe only for OAuth-backed setup and keeps direct validation for Nous API key setup. For more information, refer to [NemoClaw Inference Options](../inference/inference-options). ## v0.0.53 @@ -280,4 +280,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. +See [Checking the OpenClaw version](../reference/commands#checking-the-openclaw-version) for the full policy. diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index fc577f2e0f..faa86f634f 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -54,7 +54,7 @@ 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. No manual setup is required. -See the [troubleshooting guide](/reference/troubleshooting) for the override knobs and a manual `daemon.json` alternative. +See the [troubleshooting guide](../reference/troubleshooting) for the override knobs and a manual `daemon.json` alternative. ## Platforms @@ -74,6 +74,6 @@ The table is generated from [`ci/platform-matrix.json`](https://github.com/NVIDI ## Next Steps -- [Prepare Windows for NemoClaw](/get-started/windows-preparation) if you are using Windows. -- [Quickstart](/get-started/quickstart) to install NemoClaw and launch your first sandbox. -- [Agent Skills](/resources/agent-skills) to load NemoClaw guidance into an AI coding assistant before setup. +- [Prepare Windows for NemoClaw](windows-preparation) if you are using Windows. +- [Quickstart](quickstart) to install NemoClaw and launch your first sandbox. +- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant before setup. diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index 2d54fb5731..7ff6799a3b 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -14,7 +14,7 @@ skill: Use NemoHermes when you want NemoClaw to create an OpenShell sandbox that runs Hermes instead of the default OpenClaw agent. The `nemohermes` command is an alias for `nemoclaw` with the Hermes agent pre-selected. -Review the [Prerequisites](/get-started/prerequisites) before starting. +Review the [Prerequisites](prerequisites) before starting. Docker must be installed, running, and reachable from the current shell before Hermes onboarding can build the sandbox image. On Linux, the installer can install Docker, start the service, and add your user to the `docker` group. If it changes group membership, run the printed `newgrp docker` recovery command before rerunning the installer. @@ -67,7 +67,7 @@ Sandbox name [hermes]: my-hermes Choose the inference provider that matches where you want Hermes model traffic to go. The provider options and credential environment variables are the same as the standard NemoClaw quickstart. -For provider-specific prompts, refer to the [Respond to the Onboard Wizard](/get-started/quickstart#respond-to-the-onboard-wizard) section and the [Inference Options](/inference/inference-options) page. +For provider-specific prompts, refer to the [Inference Options](../inference/inference-options) page. The Hermes wizard does not ask for Brave Web Search because Hermes does not use NemoClaw's OpenClaw web-search configuration. After provider and model selection, review the summary and confirm the build. @@ -93,7 +93,7 @@ $ export NVIDIA_API_KEY= $ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ``` -Use the provider variables from [Inference Options](/inference/inference-options) when you choose a different provider. +Use the provider variables from [Inference Options](../inference/inference-options) when you choose a different provider. ## Connect to Hermes @@ -217,7 +217,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) 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. diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index ceaf993168..560306644d 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -14,13 +14,13 @@ skill: Follow these steps to get started with NemoClaw and your first sandboxed OpenClaw agent. -Make sure you have completed reviewing the [Prerequisites](/get-started/prerequisites) before following this guide. +Make sure you have completed reviewing the [Prerequisites](prerequisites) before following this guide. NemoClaw ships user skills for AI coding assistants. Load them when you want your assistant to walk through installation, inference choices, policy approvals, monitoring, or troubleshooting with NemoClaw-specific guidance. -Refer to [Agent Skills](/resources/agent-skills). +Refer to [Agent Skills](../resources/agent-skills). ## Install NemoClaw and Onboard OpenClaw Agent @@ -113,14 +113,14 @@ The inference provider prompt presents a numbered list. ``` Pick the option that matches where you want inference traffic to go, then expand the matching helper below for the follow-up prompts and the API key environment variable to set. -For the full list of providers and validation behavior, refer to [Inference Options](/inference/inference-options). +For the full list of providers and validation behavior, refer to [Inference Options](../inference/inference-options). Local Ollama appears when NemoClaw detects a usable local Ollama path or can offer an install or start action for your platform. The Model Router option appears when the blueprint router profile is enabled. Export the API key before launching the installer so the wizard does not have to ask for it. For example, run `export NVIDIA_API_KEY=` before `curl ... | bash`. -If you entered a key incorrectly, refer to [Reset a Stored Credential](/manage-sandboxes/lifecycle#reset-a-stored-credential) to clear and re-enter it. +If you entered a key incorrectly, refer to [Reset a Stored Credential](../manage-sandboxes/lifecycle#reset-a-stored-credential) to clear and re-enter it. @@ -230,7 +230,7 @@ Respond to the wizard as follows. 1. At the `Choose [1]:` prompt, type `7` to select **Local Ollama**. 2. At the `Choose model [1]:` prompt, pick from **Ollama models** if any are already installed. If none are installed, pick a **starter model** to pull and load now, or pick **Other...** to enter any Ollama model ID. -For setup details, including GPU recommendations and starter model choices, refer to [Use a Local Inference Server](/inference/use-local-inference). +For setup details, including GPU recommendations and starter model choices, refer to [Use a Local Inference Server](../inference/use-local-inference). @@ -264,7 +264,7 @@ The sandbox still calls `https://inference.local/v1`, so do not point in-sandbox - **Local vLLM (already running)** appears whenever NemoClaw detects a vLLM server on `localhost:8000`. No flag is required for the menu entry. NemoClaw auto-detects the loaded model. - **Local vLLM (managed install/start)** appears by default on DGX Spark and DGX Station. Generic Linux NVIDIA GPU hosts require `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls and starts a vLLM container on supported hosts. -For setup, refer to [Use a Local Inference Server](/inference/use-local-inference). +For setup, refer to [Use a Local Inference Server](../inference/use-local-inference). ### Review the Configuration Before the Sandbox Build @@ -305,7 +305,7 @@ If you leave all channels unselected, pressing Enter skips messaging setup. If you select a channel, NemoClaw validates the token format before it bakes the channel configuration into the sandbox. For example, Slack bot tokens must start with `xoxb-`. WeChat and WhatsApp are experimental. -Review [Messaging Channels](/manage-sandboxes/messaging-channels) before enabling them. +Review [Messaging Channels](../manage-sandboxes/messaging-channels) before enabling them. ### Choose Network Policy Presets @@ -391,14 +391,14 @@ openclaw tui Navigate to the following 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. -- [Agent Skills](/resources/agent-skills) to load NemoClaw guidance into an AI coding assistant. +- [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. +- [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant. Use the following topics to learn how to use 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) 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. diff --git a/docs/get-started/windows-preparation.mdx b/docs/get-started/windows-preparation.mdx index 3f50904539..faeb6c6c8d 100644 --- a/docs/get-started/windows-preparation.mdx +++ b/docs/get-started/windows-preparation.mdx @@ -9,8 +9,15 @@ keywords: ["nemoclaw windows wsl2 setup", "nemoclaw install windows docker deskt content: type: "reference" --- +import { AgentOnly } from "../_components/AgentGuide"; + You can run NemoClaw inside Windows Subsystem for Linux (WSL 2) on Windows. -Complete these steps before following the [Quickstart](/get-started/quickstart). + +Complete these steps before following the [Quickstart](quickstart). + + +Complete these steps before following [Quickstart with Hermes](quickstart-hermes). + Linux and macOS users do not need this page and can go directly to the Quickstart. @@ -22,7 +29,16 @@ This guide has been tested on x86-64. Verify the following before you begin: - Windows 10 (build 19041 or later) or Windows 11. -- Hardware requirements are the same as the [Quickstart](/get-started/quickstart). + + +- Hardware requirements are the same as the [Quickstart](quickstart). + + + + +- Hardware requirements are the same as [Quickstart with Hermes](quickstart-hermes). + + ## Option: Use the Bootstrap Script @@ -146,10 +162,15 @@ Use one instance, or move one of them to a different port before running `nemocl Your Windows environment is ready. If you used the bootstrap script, follow the installer command it printed inside Ubuntu. -If you prepared Windows manually, open a WSL terminal (type `wsl` in PowerShell, or open Ubuntu from Windows Terminal) and continue with the [Quickstart](/get-started/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 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-hermes) to install NemoClaw and launch your first Hermes sandbox. + All NemoClaw commands run inside WSL, not in PowerShell. ## Troubleshooting -For Windows-specific troubleshooting, refer to the [Windows Subsystem for Linux section](/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/index.yml b/docs/index.yml index 4d87db8833..2f17ed81ba 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -213,14 +213,9 @@ navigation: - page: "Use Local Inference" path: inference/use-local-inference.mdx slug: use-local-inference - - page: "Tool-Calling Reliability" - path: inference/tool-calling-reliability.mdx - slug: tool-calling-reliability - page: "Switch Inference Providers" path: inference/switch-inference-providers.mdx slug: switch-inference-providers - - page: "Set Up Task-Specific Sub-Agents" - path: inference/set-up-sub-agent.mdx - section: "Manage Sandboxes" slug: manage-sandboxes collapsed: open-by-default @@ -240,6 +235,9 @@ navigation: - page: "Backup and Restore" path: manage-sandboxes/backup-restore.mdx slug: backup-restore + - page: "Install Hermes Plugins" + path: manage-sandboxes/install-plugins-hermes.mdx + slug: install-plugins-hermes - section: "Network Policy" slug: network-policy collapsed: open-by-default @@ -253,22 +251,6 @@ navigation: - page: "Integration Policy Examples" path: network-policy/integration-policy-examples.mdx slug: integration-policy-examples - - section: "Deployment" - slug: deployment - collapsed: open-by-default - contents: - - page: "Deploy to Remote GPU Instances" - path: deployment/deploy-to-remote-gpu.mdx - slug: deploy-to-remote-gpu - - page: "Brev Web UI" - path: deployment/brev-web-ui.mdx - slug: brev-web-ui - - page: "Install OpenClaw Plugins" - path: deployment/install-openclaw-plugins.mdx - slug: install-openclaw-plugins - - page: "Sandbox Hardening" - path: deployment/sandbox-hardening.mdx - slug: sandbox-hardening - section: "Monitoring" slug: monitoring collapsed: open-by-default @@ -286,9 +268,9 @@ navigation: - page: "Credential Storage" path: security/credential-storage.mdx slug: credential-storage - - page: "OpenClaw Controls" - path: security/openclaw-controls.mdx - slug: openclaw-controls + - page: "Hermes Controls" + path: security/hermes-controls.mdx + slug: hermes-controls - section: "Reference" slug: reference collapsed: open-by-default diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index 3b7ef7a68c..268d6ab1b6 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -9,10 +9,22 @@ keywords: ["nemoclaw inference options", "nemoclaw onboarding providers", "nemoc content: type: "concept" --- +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw supports multiple inference providers. -During onboarding, the `nemoclaw onboard` wizard presents a numbered list of providers to choose from. +During onboarding, the NemoClaw onboarding wizard presents a numbered list of providers to choose from. Your selection determines where the agent's inference traffic is routed. + +For OpenClaw onboarding, use `nemoclaw onboard`. +The provider flow is the same, with the NVIDIA Endpoints route available for OpenClaw Agent. + + + +For Hermes onboarding, use `nemohermes onboard`. +The provider flow is the same, with the Hermes Provider route available for Hermes Agent. + + ## How Inference Routing Works The agent inside the sandbox talks to `inference.local`. @@ -59,7 +71,7 @@ The managed install/start vLLM entry appears by default on DGX Spark and DGX Sta | Other Anthropic-compatible endpoint | Routes to any server that implements the Anthropic Messages API (`/v1/messages`). 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](/inference/use-local-inference). | +| 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). | | Model Router | Starts a host-side router on port `4000`, registers it as an OpenAI-compatible provider, and keeps the sandbox pointed at `inference.local`. Set `NEMOCLAW_PROVIDER=routed` for non-interactive setup. | The router pool defines the model names. | ## Choosing the Right Option for Nemotron @@ -125,11 +137,19 @@ The sandbox never sees raw API keys. To use the router in scripted setup, set: + ```console $ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemoclaw onboard --non-interactive ``` + -### Host Python requirement + +```console +$ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY= nemohermes onboard --non-interactive +``` + + +### Host Python Requirement The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding. NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of: @@ -140,11 +160,24 @@ NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare 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. + To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`: + + +To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemohermes onboard`: + + ```console $ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard ``` + + + +```console +$ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemohermes onboard +``` + The pin is strict. NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`. @@ -162,7 +195,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](/inference/use-local-inference). +For setup instructions, refer to [Use a Local Inference Server](use-local-inference). ## Validation @@ -185,6 +218,6 @@ Other provider credentials, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMI ## Next Steps -- [Use a Local Inference Server](/inference/use-local-inference) for Ollama, vLLM, NIM, and compatible-endpoint setup details. -- [Tool-Calling Reliability](/inference/tool-calling-reliability) for deciding when Ollama is enough and when vLLM with a parser is safer. -- [Switch Inference Models](/inference/switch-inference-providers) for changing the model at runtime without re-onboarding. +- [Use a Local Inference Server](use-local-inference) for Ollama, vLLM, NIM, and compatible-endpoint setup details. +- [Tool-Calling Reliability](tool-calling-reliability) for deciding when Ollama is enough and when vLLM with a parser is safer. +- [Switch Inference Models](switch-inference-providers) for changing the model at runtime without re-onboarding. diff --git a/docs/inference/set-up-sub-agent.mdx b/docs/inference/set-up-sub-agent.mdx index 231988663d..2ad8c03c9a 100644 --- a/docs/inference/set-up-sub-agent.mdx +++ b/docs/inference/set-up-sub-agent.mdx @@ -97,7 +97,7 @@ $ docker exec "$DOCKER_CTR" kubectl exec -n openshell "$SANDBOX" -c agent -- cho If the sub-agent calls a provider directly, update the OpenShell network policy for the binary that makes the request. In the Omni demo, the OpenClaw gateway runs as `/usr/local/bin/node`, so the NVIDIA endpoint policy must allow that binary. -Refer to [Customize the Network Policy](/network-policy/customize-network-policy) for policy update workflows. +Refer to [Customize the Network Policy](../network-policy/customize-network-policy) for policy update workflows. ## Add Delegation Instructions @@ -125,5 +125,5 @@ Use the [`vlm-demo`](https://github.com/brevdev/nemoclaw-demos/tree/main/vlm-dem Use the following resources for more information: - 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](/inference/switch-inference-providers) to change the primary orchestration model instead of adding a sub-agent model. -- Refer to [Workspace Files](/manage-sandboxes/workspace-files) to understand per-agent workspace directories. +- Refer to [Switch Inference Providers](switch-inference-providers) to change the primary orchestration model instead of adding a sub-agent model. +- Refer to [Workspace Files](../manage-sandboxes/workspace-files) to understand per-agent workspace directories. diff --git a/docs/inference/switch-inference-providers.mdx b/docs/inference/switch-inference-providers.mdx index 7c276df638..4db966b53b 100644 --- a/docs/inference/switch-inference-providers.mdx +++ b/docs/inference/switch-inference-providers.mdx @@ -11,6 +11,8 @@ content: skill: priority: 20 --- +import { AgentOnly } from "../_components/AgentGuide"; + Change the active inference model while the sandbox is running. No restart is required. @@ -21,42 +23,80 @@ No restart is required. ## Switch to a Different Model + Use `nemoclaw inference set` with the provider and model that match the upstream you want to use. The command updates the OpenShell inference route and synchronizes the running agent config. For OpenClaw, it updates `agents.defaults.model.primary` and the matching provider namespace. + + +Use `nemohermes inference set` with the provider and model that match the upstream you want to use. +The command updates the OpenShell inference route and synchronizes the running agent config. For Hermes, it updates `/sandbox/.hermes/config.yaml` (`model.default`, `model.base_url`, and `model.provider: custom`) without rebuilding or restarting Hermes. - Pass `--sandbox ` when you do not want to use the default registered sandbox. Under `nemohermes`, pass `--sandbox ` when more than one Hermes sandbox is registered. + + + +Pass `--sandbox ` when you do not want to use the default registered sandbox. + ### NVIDIA Endpoints + ```console $ nemoclaw inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b ``` + + +```console +$ nemohermes inference set --provider nvidia-prod --model nvidia/nemotron-3-super-120b-a12b +``` + ### OpenAI + ```console $ nemoclaw inference set --provider openai-api --model gpt-5.4 ``` + + +```console +$ nemohermes inference set --provider openai-api --model gpt-5.4 +``` + ### Anthropic + ```console $ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 ``` + + +```console +$ nemohermes inference set --provider anthropic-prod --model claude-sonnet-4-6 +``` + ### Google Gemini + ```console $ nemoclaw inference set --provider gemini-api --model gemini-2.5-flash ``` + + +```console +$ nemohermes inference set --provider gemini-api --model gemini-2.5-flash +``` + ### Compatible Endpoints If you onboarded a custom compatible endpoint, switch models with the provider created for that endpoint: + ```console $ nemoclaw inference set --provider compatible-endpoint --model ``` @@ -64,6 +104,18 @@ $ nemoclaw inference set --provider compatible-endpoint --model ```console $ nemoclaw inference set --provider compatible-anthropic-endpoint --model ``` + + +```console +$ nemohermes inference set --provider compatible-endpoint --model +``` + +```console +$ nemohermes inference set --provider compatible-anthropic-endpoint --model +``` + + + ### Hermes Provider @@ -73,6 +125,8 @@ For a NemoClaw-managed Hermes sandbox, use the Hermes alias with the registered $ nemohermes inference set --provider hermes-provider --model openai/gpt-5.4-mini ``` + + #### Switching from Responses API to Chat Completions If onboarding selected `/v1/responses` but the agent fails at runtime (for @@ -80,10 +134,16 @@ example, because the backend does not emit the streaming events OpenClaw requires), re-run onboarding so the wizard re-probes the endpoint and bakes the correct API path into the image: + ```console $ nemoclaw onboard ``` - + + +```console +$ nemohermes onboard +``` + Select the same provider and endpoint again. The updated streaming probe will detect incomplete `/v1/responses` support and select `/v1/chat/completions` automatically. @@ -93,34 +153,62 @@ default, so no env var is required to keep the safe path. To opt in to `/v1/responses` for a backend you have verified end to end, set `NEMOCLAW_PREFERRED_API` before onboarding: + ```console $ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard ``` + + +```console +$ NEMOCLAW_PREFERRED_API=openai-responses nemohermes onboard +``` + `NEMOCLAW_INFERENCE_API_OVERRIDE` patches the config at container startup but does not update the Dockerfile ARG baked into the image. If you recreate the sandbox without the override env var, the image reverts to the original API path. + A fresh `nemoclaw onboard` is the reliable fix because it updates both the session and the baked image. + + +A fresh `nemohermes onboard` is the reliable fix because it updates both the +session and the baked image. + ## Cross-Provider Switching + Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemoclaw inference set`. The command updates both the gateway route and the OpenClaw provider namespace in the running sandbox config. ```console $ nemoclaw inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify ``` + + +Switching to a different provider family (for example, from NVIDIA Endpoints to Anthropic) also uses `nemohermes inference set`. +The command updates both the gateway route and `/sandbox/.hermes/config.yaml`. + +```console +$ nemohermes inference set --provider anthropic-prod --model claude-sonnet-4-6 --no-verify +``` + Use `--no-verify` only when OpenShell cannot verify the provider at switch time but you have already confirmed the provider and credential. ## Tune Model Metadata The sandbox image bakes model metadata (context window, max output tokens, reasoning mode, and accepted input modalities) into `openclaw.json` at build time. + To change these values, set the corresponding environment variables before running `nemoclaw onboard` so they patch into the Dockerfile before the image builds. + + +To change these values, set the corresponding environment variables before running `nemohermes onboard` so they patch into the Dockerfile before the image builds. + | Variable | Values | Default | |---|---|---| @@ -135,6 +223,7 @@ Invalid values are ignored, and the default bakes into the image. For Local Ollama, onboarding loads the selected model first and uses Ollama's reported runtime context length when `NEMOCLAW_CONTEXT_WINDOW` is unset. Use `NEMOCLAW_INFERENCE_INPUTS=text,image` only for a model that accepts image input through the selected provider. + ```console $ export NEMOCLAW_CONTEXT_WINDOW=65536 $ export NEMOCLAW_MAX_TOKENS=8192 @@ -144,6 +233,20 @@ $ export NEMOCLAW_AGENT_TIMEOUT=1800 $ export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m $ nemoclaw onboard ``` + + +```console +$ export NEMOCLAW_CONTEXT_WINDOW=65536 +$ export NEMOCLAW_MAX_TOKENS=8192 +$ export NEMOCLAW_REASONING=true +$ export NEMOCLAW_INFERENCE_INPUTS=text,image +$ export NEMOCLAW_AGENT_TIMEOUT=1800 +$ export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m +$ nemohermes onboard +``` + + + `NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into `agents.defaults.timeoutSeconds`. Increase it for slow local inference (for @@ -153,6 +256,19 @@ file writable for agent state, but direct in-sandbox edits are not the supported or durable way to change NemoClaw-managed defaults. Rebuild the sandbox via `nemoclaw onboard` to apply a new value. + + + +`NEMOCLAW_AGENT_TIMEOUT` controls the per-request inference timeout baked into +the Hermes sandbox image. Increase it for slow local inference (for example, +CPU-only Ollama or vLLM on modest hardware). Direct in-sandbox edits are not the +supported or durable way to change NemoClaw-managed defaults. Rebuild the +sandbox via `nemohermes onboard` to apply a new value. + + + + + `NEMOCLAW_AGENT_HEARTBEAT_EVERY` sets `agents.defaults.heartbeat.every`. This controls OpenClaw's periodic main-session agent turn. Each interval, the agent wakes up to review follow-ups and read `HEARTBEAT.md` if present in the workspace. @@ -164,15 +280,32 @@ The in-sandbox `openclaw config set` command is not the supported path for NemoClaw-managed build-time defaults, and direct file edits are overwritten by a rebuild. Rebuild the sandbox via `nemoclaw onboard --resume` to apply a new value. + + + +Hermes does not use OpenClaw's `HEARTBEAT.md` wake-up mechanism. Rebuild the +sandbox via `nemohermes onboard --resume` to apply build-time inference +metadata changes. + + + These variables are build-time settings. If you change them on an existing sandbox, recreate the sandbox so the new values bake into the image: + ```console $ nemoclaw onboard --resume --recreate-sandbox ``` + + +```console +$ nemohermes onboard --resume --recreate-sandbox +``` + ## Verify the Active Model + Use `nemoclaw inference get` to print the provider and model the gateway is currently routing to. Run it before `nemoclaw inference set` to confirm the starting state, or after a switch to verify the new route. @@ -191,26 +324,72 @@ $ nemoclaw inference get --json "model": "nvidia/nemotron-3-super-120b-a12b" } ``` + + +Use `nemohermes inference get` to print the provider and model the gateway is currently routing to. +Run it before `nemohermes inference set` to confirm the starting state, or after a switch to verify the new route. + +```console +$ nemohermes inference get +Provider: nvidia-prod +Model: nvidia/nemotron-3-super-120b-a12b +``` + +Pass `--json` for machine-readable output. + +```console +$ nemohermes inference get --json +{ + "provider": "nvidia-prod", + "model": "nvidia/nemotron-3-super-120b-a12b" +} +``` + The command exits non-zero with `OpenShell inference route is not configured.` when the gateway has no registered inference route. + Run `nemoclaw onboard` to configure one. + + +Run `nemohermes onboard` to configure one. + Run the status command when you also need sandbox, service, and messaging health: + ```console $ nemoclaw status ``` + + +```console +$ nemohermes status +``` + The status output includes the active provider, model, and endpoint with the rest of the sandbox state. ## Notes + + - The host keeps provider credentials. - The sandbox continues to use `inference.local`. - `nemoclaw inference set` patches the selected running OpenClaw or Hermes sandbox config and recomputes its config hash. - Use `nemoclaw onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. - Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. + + + +- The host keeps provider credentials. +- The sandbox continues to use `inference.local`. +- `nemohermes inference set` patches the selected running Hermes sandbox config and recomputes its config hash. +- Use `nemohermes onboard --resume --recreate-sandbox` for build-time settings such as context window, max tokens, reasoning mode, heartbeat cadence, or image contents. +- Local Ollama and local vLLM routes use local provider tokens rather than `OPENAI_API_KEY`. Rebuilds of older local-inference sandboxes clear the stale OpenAI credential requirement automatically. + + + ## Related Topics -- [Inference Options](/inference/inference-options) for the full list of providers available during onboarding. +- [Inference Options](inference-options) for the full list of providers available during onboarding. diff --git a/docs/inference/tool-calling-reliability.mdx b/docs/inference/tool-calling-reliability.mdx index 1f3a0d4b96..11cbece4d0 100644 --- a/docs/inference/tool-calling-reliability.mdx +++ b/docs/inference/tool-calling-reliability.mdx @@ -166,6 +166,6 @@ model. ## Next Steps -- [Use a Local Inference Server](/inference/use-local-inference) -- [Inference Options](/inference/inference-options) -- [Switch Inference Models](/inference/switch-inference-providers) +- [Use a Local Inference Server](use-local-inference) +- [Inference Options](inference-options) +- [Switch Inference Models](switch-inference-providers) diff --git a/docs/inference/use-local-inference.mdx b/docs/inference/use-local-inference.mdx index 76c00c4a05..f071881e3f 100644 --- a/docs/inference/use-local-inference.mdx +++ b/docs/inference/use-local-inference.mdx @@ -11,6 +11,8 @@ content: skill: priority: 10 --- +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw can route inference to a model server running on your machine instead of a cloud API. This page covers Ollama, compatible-endpoint paths for other servers, and experimental managed options for vLLM and NVIDIA NIM. @@ -20,8 +22,12 @@ 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 yet. + + +- NemoClaw installed. Refer to [Quickstart with Hermes](../get-started/quickstart-hermes) if you have not installed yet. + - A local model server running, or a supported Ollama, vLLM, or NIM setup that the NemoClaw onboard wizard can use, start, or install. ## Ollama @@ -64,9 +70,16 @@ The user-local path cannot bootstrap system packages without elevation, so if `z Run the onboard wizard. + ```console $ nemoclaw onboard ``` + + +```console +$ nemohermes onboard +``` + Select **Local Ollama** from the provider list. NemoClaw lists installed models or offers starter models if none are installed. @@ -105,7 +118,7 @@ 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](/inference/tool-calling-reliability). +`--tool-call-parser`. See [Tool-Calling Reliability](tool-calling-reliability). ### Authenticated Reverse Proxy @@ -133,10 +146,18 @@ For non-WSL Ollama setups, the onboard wizard manages the proxy automatically: On native Linux hosts, a firewall can allow the host proxy health check while still blocking sandbox containers on the OpenShell Docker bridge. When the sandbox-side proxy probe fails with a TCP error, onboarding exits before it saves the inference route and prints a command like: + ```console $ sudo ufw allow from to any port 11435 proto tcp $ nemoclaw onboard ``` + + +```console +$ sudo ufw allow from to any port 11435 proto tcp +$ nemohermes onboard +``` + If the probe cannot run, for example because Docker Desktop or WSL uses a different host routing model, onboarding continues and relies on the regular proxy health check. @@ -162,11 +183,20 @@ This does not delete downloaded model files. ### Non-Interactive Setup + ```console $ NEMOCLAW_PROVIDER=ollama \ NEMOCLAW_MODEL=qwen2.5:14b \ nemoclaw onboard --non-interactive --yes ``` + + +```console +$ NEMOCLAW_PROVIDER=ollama \ + NEMOCLAW_MODEL=qwen2.5:14b \ + nemohermes onboard --non-interactive --yes +``` + If `NEMOCLAW_MODEL` is not set, NemoClaw selects a default model based on available memory. If `NEMOCLAW_MODEL` names a known bootstrap model (for example `qwen3.6:35b`) that does not fit the host's currently available GPU memory, NemoClaw warns and falls back to the largest known model that does fit. @@ -198,9 +228,17 @@ $ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 Run the onboard wizard. + ```console $ nemoclaw onboard ``` + + + +```console +$ nemohermes onboard +``` + When the wizard asks you to choose an inference provider, select **Other OpenAI-compatible endpoint**. Enter the base URL of your local server, for example `http://localhost:8000/v1`. @@ -218,6 +256,7 @@ Route, configuration, and authentication failures still fail immediately. Set the following environment variables for scripted or CI/CD deployments. + ```console $ NEMOCLAW_PROVIDER=custom \ NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ @@ -225,6 +264,17 @@ $ NEMOCLAW_PROVIDER=custom \ COMPATIBLE_API_KEY=dummy \ nemoclaw onboard --non-interactive ``` + + + +```console +$ NEMOCLAW_PROVIDER=custom \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8000/v1 \ + NEMOCLAW_MODEL=meta-llama/Llama-3.1-8B-Instruct \ + COMPATIBLE_API_KEY=dummy \ + nemohermes onboard --non-interactive +``` + | Variable | Purpose | |---|---| @@ -241,9 +291,16 @@ without probing the Responses API. To opt in to `/v1/responses`, set `NEMOCLAW_PREFERRED_API` before running onboard: + ```console $ NEMOCLAW_PREFERRED_API=openai-responses nemoclaw onboard ``` + + +```console +$ NEMOCLAW_PREFERRED_API=openai-responses nemohermes onboard +``` + The wizard then probes `/v1/responses` and only selects it when streaming support is complete. @@ -255,21 +312,33 @@ You can use this variable in both interactive and non-interactive mode. |---|---|---| | `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 + +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](/inference/switch-inference-providers) for details. + + +If you already onboarded and the sandbox is failing at runtime, re-run `nemohermes 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 If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead. + ```console $ nemoclaw onboard ``` - + + +```console +$ nemohermes onboard +``` + For non-interactive setup, use `NEMOCLAW_PROVIDER=anthropicCompatible` and set `COMPATIBLE_ANTHROPIC_API_KEY`. + ```console $ NEMOCLAW_PROVIDER=anthropicCompatible \ NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ @@ -277,17 +346,28 @@ $ NEMOCLAW_PROVIDER=anthropicCompatible \ COMPATIBLE_ANTHROPIC_API_KEY=dummy \ nemoclaw onboard --non-interactive ``` + + +```console +$ NEMOCLAW_PROVIDER=anthropicCompatible \ + NEMOCLAW_ENDPOINT_URL=http://localhost:8080 \ + NEMOCLAW_MODEL=my-model \ + COMPATIBLE_ANTHROPIC_API_KEY=dummy \ + nemohermes onboard --non-interactive +``` + ## vLLM When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model. On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you. + For an already-running vLLM server, run `nemoclaw onboard` and select **Local vLLM [experimental]** from the provider list. - -```console -$ nemoclaw onboard -``` + + +For an already-running vLLM server, run `nemohermes onboard` and select **Local vLLM [experimental]** from the provider list. + If vLLM is already running, NemoClaw detects the running model and validates the endpoint. If vLLM is not running and your host matches a DGX Spark or DGX Station managed profile, NemoClaw shows the **Install vLLM** or **Start vLLM** entry by default. @@ -313,18 +393,34 @@ The vLLM `/v1/responses` endpoint does not run the `--tool-call-parser`, so tool Use an already-running vLLM server: + ```console $ NEMOCLAW_PROVIDER=vllm \ nemoclaw onboard --non-interactive ``` + + +```console +$ NEMOCLAW_PROVIDER=vllm \ + nemohermes onboard --non-interactive +``` + Install or start managed vLLM when a supported profile is detected. On DGX Spark and DGX Station, `NEMOCLAW_PROVIDER=install-vllm` is enough for non-interactive runs; add `NEMOCLAW_EXPERIMENTAL=1` on generic Linux NVIDIA GPU hosts. + ```console $ NEMOCLAW_PROVIDER=install-vllm \ nemoclaw onboard --non-interactive ``` + + +```console +$ NEMOCLAW_PROVIDER=install-vllm \ + nemohermes onboard --non-interactive +``` + NemoClaw records the model returned by vLLM's `/v1/models` endpoint. Start vLLM with the model you want before onboarding if you manage the server yourself. @@ -347,12 +443,22 @@ An unrecognised value fails fast with a list of valid slugs. Gated models require a Hugging Face token; export it before onboarding so NemoClaw can forward it into the managed vLLM container: + ```console $ export HF_TOKEN= $ NEMOCLAW_PROVIDER=install-vllm \ NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ nemoclaw onboard --non-interactive ``` + + +```console +$ export HF_TOKEN= +$ NEMOCLAW_PROVIDER=install-vllm \ + NEMOCLAW_VLLM_MODEL=deepseek-r1-distill-70b \ + nemohermes onboard --non-interactive +``` + `HUGGING_FACE_HUB_TOKEN` is accepted as an alternative. The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401. @@ -363,9 +469,16 @@ NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable Set the experimental flag and run onboard. + ```console $ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard ``` + + +```console +$ NEMOCLAW_EXPERIMENTAL=1 nemohermes onboard +``` + Select **Local NVIDIA NIM [experimental]** from the provider list. NemoClaw filters available models by GPU VRAM, pulls the NIM container image, starts it, and waits for it to become healthy before continuing. @@ -374,7 +487,12 @@ On hosts with mixed NVIDIA GPU models, the preflight summary shows each detected NIM container images are hosted on `nvcr.io` and require NGC registry authentication before `docker pull` succeeds. If Docker is not already logged in to `nvcr.io`, onboard prompts for an [NGC API key](https://org.ngc.nvidia.com/setup/api-key) and runs `docker login nvcr.io` over `--password-stdin` so the key is never written to disk or shell history. The prompt masks the key during input and retries once on a bad key before failing. + In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemoclaw onboard --non-interactive`. + + +In non-interactive mode, onboard exits with login instructions if Docker is not already authenticated; run `docker login nvcr.io` yourself, then re-run `nemohermes onboard --non-interactive`. + If `NGC_API_KEY` or `NVIDIA_API_KEY` is already exported, NemoClaw passes it into the managed NIM container through the process environment instead of command-line arguments. If the NIM container exits before the health endpoint becomes ready, onboarding stops early and prints the last container log lines. @@ -385,11 +503,20 @@ The same `chat/completions` API path restriction applies. ### Non-Interactive Setup + ```console $ NEMOCLAW_EXPERIMENTAL=1 \ NEMOCLAW_PROVIDER=nim \ nemoclaw onboard --non-interactive ``` + + +```console +$ NEMOCLAW_EXPERIMENTAL=1 \ + NEMOCLAW_PROVIDER=nim \ + nemohermes onboard --non-interactive +``` + To select a specific model, set `NEMOCLAW_MODEL`. @@ -400,14 +527,27 @@ Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so Nemo To override the timeout, set the `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` environment variable before onboarding: + ```console $ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 $ nemoclaw onboard ``` + + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ nemohermes onboard +``` + The value is in seconds. This setting is baked into the sandbox at build time. + Changing it after onboarding requires re-running `nemoclaw onboard`. + + +Changing it after onboarding requires re-running `nemohermes onboard`. + `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` only governs the inference-server validation probe. During local Ollama setup, NemoClaw treats host-side curl process timeouts as retryable probe failures and retries with a larger timeout before it reports a validation failure. @@ -415,21 +555,37 @@ NemoClaw also retries Docker runtime detection with a longer `docker info` timeo The post-create readiness wait (image build, gateway upload, in-sandbox boot) has its own budget, `NEMOCLAW_SANDBOX_READY_TIMEOUT`, also defaulting to 180 seconds. On hosts where the sandbox image takes minutes to build or upload — large quantised models, DGX Station first runs, or remote VMs over a slow link — raise both together: + ```console $ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 $ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 $ nemoclaw onboard ``` + + +```console +$ export NEMOCLAW_LOCAL_INFERENCE_TIMEOUT=300 +$ export NEMOCLAW_SANDBOX_READY_TIMEOUT=600 +$ nemohermes onboard +``` + -If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to [Troubleshooting](/reference/troubleshooting#sandbox-onboard-times-out-with-did-not-become-ready-within-ns). +If onboard ends with `Sandbox '' was created but did not become ready within 180s`, refer to [Troubleshooting](../reference/troubleshooting#sandbox-onboard-times-out-with-did-not-become-ready-within-ns). ## Verify the Configuration After onboarding completes, confirm the active provider and model. + ```console $ nemoclaw status ``` + + +```console +$ nemohermes status +``` + The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-compatible endpoint") and the active model. For Local Ollama, status also checks the authenticated proxy when a proxy token is available. @@ -438,19 +594,42 @@ 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. -Refer to [Switch Inference Models](/inference/switch-inference-providers) for the full procedure. +Refer to [Switch Inference Models](switch-inference-providers) for the full procedure. For compatible endpoints, the command is: + ```console $ nemoclaw inference set --provider compatible-endpoint --model ``` + + +```console +$ nemohermes inference set --provider compatible-endpoint --model +``` + + If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemoclaw inference set`. + + +If the provider itself needs to change (for example, switching from vLLM to a cloud API), pass the new provider to `nemohermes inference set`. + ## Next Steps -- [Inference Options](/inference/inference-options) for the full list of providers available during onboarding. -- [Tool-Calling Reliability](/inference/tool-calling-reliability) for diagnosing raw JSON tool-call output with local models. -- [Switch Inference Models](/inference/switch-inference-providers) for runtime model switching. -- [Quickstart](/get-started/quickstart) for first-time installation. + + +- [Inference Options](inference-options) for the full list of providers available during onboarding. +- [Tool-Calling Reliability](tool-calling-reliability) for diagnosing raw JSON tool-call output with local models. +- [Switch Inference Models](switch-inference-providers) for runtime model switching. +- [Quickstart](../get-started/quickstart) for first-time installation. + + + + +- [Inference Options](inference-options) for the full list of providers available during onboarding. +- [Switch Inference Models](switch-inference-providers) for runtime model switching. +- [Quickstart with Hermes](../get-started/quickstart-hermes) for first-time installation. + + diff --git a/docs/manage-sandboxes/backup-restore.mdx b/docs/manage-sandboxes/backup-restore.mdx index 4f21e881e5..26af3369d8 100644 --- a/docs/manage-sandboxes/backup-restore.mdx +++ b/docs/manage-sandboxes/backup-restore.mdx @@ -11,17 +11,30 @@ content: skill: priority: 20 --- -Workspace files define your agent's personality, memory, and user context. -They persist across sandbox restarts but are **permanently deleted** when you run `nemoclaw destroy`. +import { AgentOnly } from "../_components/AgentGuide"; + +Workspace and state files define your agent's personality, memory, user context, and durable runtime state. +They persist across sandbox restarts but are **permanently deleted** when you destroy the sandbox. This guide covers snapshot commands, manual backup with CLI commands, and an automated script. ## When to Back Up -- **Before running `nemoclaw destroy`** + + +- Before running `nemoclaw destroy` - Before major NemoClaw version upgrades - Periodically, if you've invested time customizing your agent + + + +- Before running `nemohermes destroy` +- Before major NemoClaw version upgrades +- Periodically, if you've invested time customizing your agent or paired messaging channels + + + ## Snapshot Commands The fastest way to back up and restore sandbox state is with the built-in snapshot commands. @@ -33,49 +46,94 @@ instead of copying a live raw database file. Treat snapshot directories as private local data: the Hermes database can contain session metadata and message history needed for a faithful restore. + ```console $ nemoclaw my-assistant snapshot create $ nemoclaw my-assistant snapshot list $ nemoclaw my-assistant snapshot restore ``` + + +```console +$ nemohermes my-assistant snapshot create +$ nemohermes my-assistant snapshot list +$ nemohermes my-assistant snapshot restore +``` + `snapshot list` prints a table of version, name, timestamp, and path. Versions (`v1`, `v2`, ..., `vN`) are computed from the timestamp order, so `vN` is always the newest snapshot. To tag a snapshot with a human-readable label, pass `--name`: + ```console $ nemoclaw my-assistant snapshot create --name before-upgrade ``` + + +```console +$ nemohermes my-assistant snapshot create --name before-upgrade +``` + To restore a specific snapshot instead of the latest, pass a version, name, or timestamp prefix: + ```console $ nemoclaw my-assistant snapshot restore v3 $ nemoclaw my-assistant snapshot restore before-upgrade $ nemoclaw my-assistant snapshot restore 2026-04-14T ``` + + +```console +$ nemohermes my-assistant snapshot restore v3 +$ nemohermes my-assistant snapshot restore before-upgrade +$ nemohermes my-assistant snapshot restore 2026-04-14T +``` + To clone a snapshot into a different sandbox name, pass `--to `. If the destination sandbox already exists, NemoClaw refuses to overwrite it unless you pass `--force`: + ```console $ nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone $ nemoclaw my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes ``` + + +```console +$ nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone +$ nemohermes my-assistant snapshot restore before-upgrade --to my-assistant-clone --force --yes +``` + + + The `nemoclaw rebuild` command uses the same snapshot mechanism automatically. Snapshot restore performs a targeted repair for legacy `.openclaw-data` symlinks that were created by older images. Unsafe symlinks and hard links inside sandbox state are rejected during backup creation before they can enter a snapshot. + + + + +The `nemohermes rebuild` command uses the same snapshot mechanism automatically. +Unsafe symlinks and hard links inside sandbox state are rejected during backup creation before they can enter a snapshot. Credential-bearing Hermes files such as `auth.json` are intentionally excluded from snapshots. NemoClaw-regenerated Hermes config files (`config.yaml` and `.env`) are also excluded; model/provider and messaging credentials are recreated from host-side onboarding and OpenShell provider state during rebuild. -For full details, see the [Commands reference](/reference/commands). + + +For full details, see the [Commands reference](../reference/commands). ## Manual Backup Use `openshell sandbox download` to copy files from the sandbox to your host. + + ```console $ SANDBOX=my-assistant $ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) @@ -89,10 +147,27 @@ $ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/MEMORY.md " $ openshell sandbox download "$SANDBOX" /sandbox/.openclaw/workspace/memory/ "$BACKUP_DIR/memory/" ``` + + + +```console +$ SANDBOX=my-hermes +$ BACKUP_DIR=~/.nemoclaw/backups/$(date +%Y%m%d-%H%M%S) +$ mkdir -p "$BACKUP_DIR" + +$ openshell sandbox download "$SANDBOX" /sandbox/SOUL.md "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.hermes/state.db "$BACKUP_DIR/" +$ openshell sandbox download "$SANDBOX" /sandbox/.hermes/platforms/ "$BACKUP_DIR/platforms/" +``` + + + ## Manual Restore Use `openshell sandbox upload` to push files back into a sandbox. + + ```console $ SANDBOX=my-assistant $ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp @@ -105,8 +180,24 @@ $ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/MEMORY.md" /sandbox/.openclaw $ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/memory/" /sandbox/.openclaw/workspace/memory/ ``` + + + +```console +$ SANDBOX=my-hermes +$ BACKUP_DIR=~/.nemoclaw/backups/20260320-120000 # pick a timestamp + +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/SOUL.md" /sandbox/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/state.db" /sandbox/.hermes/ +$ openshell sandbox upload "$SANDBOX" "$BACKUP_DIR/platforms/" /sandbox/.hermes/platforms/ +``` + + + ## Using the Backup Script + + The repository includes a convenience script at `scripts/backup-workspace.sh`. ### Backup @@ -145,11 +236,21 @@ USER.md memory/ ``` + + + +For Hermes, prefer the built-in snapshot commands for faithful restore of `state.db`. +Use manual `openshell sandbox download` / `openshell sandbox upload` only when you need to inspect or transfer a specific file. + + + + + ## Multi-Agent Deployments When OpenClaw is configured with multiple named agents, each agent has its own workspace directory (`workspace-main/`, `workspace-support/`, `workspace-ops/`, -and so on — see [Multi-Agent Deployments](/manage-sandboxes/workspace-files#multi-agent-deployments)). +and so on — see [Multi-Agent Deployments](workspace-files#multi-agent-deployments)). `nemoclaw snapshot create` automatically discovers every `workspace-*/` directory under the sandbox state tree and includes it in the snapshot bundle @@ -169,7 +270,19 @@ editing, or maintain a host-side sync layer. Tracking shared-file tooling (shared mount, `workspaces list` command) in [#1260](https://github.com/NVIDIA/NemoClaw/issues/1260). + + + +## Hermes State + +Hermes does not use OpenClaw per-agent workspace directories. +NemoClaw snapshots preserve the Hermes manifest-defined state tree and durable +top-level files instead. See [Workspace Files](workspace-files) for the Hermes +state layout. + + + ## Next Steps -- [Workspace Files overview](/manage-sandboxes/workspace-files) to learn what each file does -- [Commands reference](/reference/commands) +- [Workspace Files overview](workspace-files) to learn what each file does. +- [Commands reference](../reference/commands) diff --git a/docs/manage-sandboxes/install-plugins-hermes.mdx b/docs/manage-sandboxes/install-plugins-hermes.mdx new file mode 100644 index 0000000000..cdd6514ee3 --- /dev/null +++ b/docs/manage-sandboxes/install-plugins-hermes.mdx @@ -0,0 +1,14 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Install Hermes Plugins" +sidebar-title: "Install Hermes Plugins" +description: "Install Hermes plugins for NemoClaw-managed sandboxes." +description-agent: "Explains how to install Hermes plugins in NemoClaw-managed sandboxes." +keywords: ["install hermes plugins", "hermes plugins nemoclaw", "nemoclaw hermes plugins"] +content: + type: "how_to" +skill: + priority: 40 +--- +TBD diff --git a/docs/manage-sandboxes/lifecycle.mdx b/docs/manage-sandboxes/lifecycle.mdx index edb8aa2954..5605deff05 100644 --- a/docs/manage-sandboxes/lifecycle.mdx +++ b/docs/manage-sandboxes/lifecycle.mdx @@ -11,68 +11,141 @@ content: skill: priority: 10 --- -Use this guide after you finish the [OpenClaw quickstart](/get-started/quickstart). +import { AgentOnly } from "../_components/AgentGuide"; + + +Use this guide after you finish the [OpenClaw quickstart](../get-started/quickstart). + + +Use this guide after you finish [Quickstart with Hermes](../get-started/quickstart-hermes). + It covers day-two sandbox operations such as listing sandboxes, checking health, managing ports, rebuilding safely, upgrading, and uninstalling. -When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](/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` and `openshell`. + + +When a workflow uses the lower-level OpenShell CLI, see [CLI Selection Guide](../reference/cli-selection-guide) for the boundary between `nemohermes`, `nemoclaw`, and `openshell`. + ## List Sandboxes List every sandbox registered on this host: + ```console $ nemoclaw list ``` + + +```console +$ nemohermes list +``` + The list shows each sandbox's model, provider, policy presets, active SSH session indicator, and dashboard URL when a dashboard port is recorded. Use JSON output for scripts: + ```console $ nemoclaw list --json ``` + + +```console +$ nemohermes list --json +``` + ## Check Sandbox Health Check a specific sandbox's health, inference route, active connections, live policy, update status, and messaging-channel overlap warnings: + ```console $ nemoclaw my-assistant status ``` + + +```console +$ nemohermes my-assistant status +``` + Use the host-level status command when you want the sandbox inventory plus host auxiliary service state, such as cloudflared: + ```console $ nemoclaw status ``` + + +```console +$ nemohermes status +``` + ## Inspect Logs View recent sandbox logs: + ```console $ nemoclaw my-assistant logs ``` + + +```console +$ nemohermes my-assistant logs +``` + Stream logs while you reproduce a problem: + ```console $ nemoclaw my-assistant logs --follow ``` + + +```console +$ nemohermes my-assistant logs --follow +``` + + The log command reads both OpenClaw gateway output and OpenShell audit events, so policy denials appear beside gateway logs. + + +The log command reads both Hermes gateway output and OpenShell audit events, so policy denials appear beside gateway logs. + ## Collect Diagnostics Collect diagnostics for bug reports or support handoff: + ```console $ nemoclaw debug --sandbox my-assistant --output nemoclaw-debug.tar.gz ``` + + +```console +$ nemohermes debug --sandbox my-assistant --output nemoclaw-debug.tar.gz +``` + Use `--quick` for a smaller local summary: + ```console $ nemoclaw debug --quick --sandbox my-assistant ``` + + +```console +$ nemohermes debug --quick --sandbox my-assistant +``` + The debug command gathers system information, Docker state, gateway logs, and sandbox status. @@ -93,27 +166,55 @@ $ openshell forward list ## Run Multiple Sandboxes Each sandbox needs its own dashboard port, since `openshell forward` refuses to bind a port that another sandbox is already using. + When the default port is already held by another sandbox, `nemoclaw onboard` scans ports `18789` through `18799` and uses the next free port. + + +When the default API port is already held by another sandbox, `nemohermes onboard` scans for the next free port and records it for the sandbox. + + ```console $ nemoclaw onboard # first sandbox uses 18789 $ nemoclaw onboard # second sandbox uses the next free port, such as 18790 ``` + + +```console +$ nemohermes onboard # first sandbox uses 18789 +$ nemohermes onboard # second sandbox uses the next free port, such as 18790 +``` + To choose a specific port, pass `--control-ui-port`: + ```console $ nemoclaw onboard --control-ui-port 19000 ``` + + +```console +$ nemohermes onboard --control-ui-port 19000 +``` + You can also set `CHAT_UI_URL` or `NEMOCLAW_DASHBOARD_PORT` before onboarding: + ```console $ CHAT_UI_URL=http://127.0.0.1:19000 nemoclaw onboard $ NEMOCLAW_DASHBOARD_PORT=19000 nemoclaw onboard ``` + + +```console +$ CHAT_UI_URL=http://127.0.0.1:19000 nemohermes onboard +$ NEMOCLAW_DASHBOARD_PORT=19000 nemohermes onboard +``` + -For full details on port conflicts and overrides, refer to [Port already in use](/reference/troubleshooting#port-already-in-use). +For full details on port conflicts and overrides, refer to [Port already in use](../reference/troubleshooting#port-already-in-use). ## Reconfigure or Recover @@ -123,74 +224,152 @@ Recover from a misconfigured sandbox without re-running the full onboard wizard Change the active model or provider at runtime without rebuilding the sandbox: + ```console $ nemoclaw inference set --model --provider ``` + + +```console +$ nemohermes inference set --model --provider +``` + -Refer to [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 + If `nemoclaw status` reports the sandbox is alive but the gateway is not running, run the recover command instead of opening a shell. + + +If `nemohermes status` reports the sandbox is alive but the Hermes gateway is not running, run the recover command instead of opening a shell. + + ```console $ nemoclaw recover ``` + + +```console +$ nemohermes 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. + +Refer to [`nemoclaw recover`](../reference/commands#nemoclaw-name-recover) for details. + + +Refer to the command reference for details on `nemohermes recover`. + ### Reset a Stored Credential If a provider credential was entered incorrectly during onboarding, clear the gateway-registered value and re-enter it on the next onboard run: + ```console $ nemoclaw credentials list # see which providers are registered $ nemoclaw credentials reset # clear a single provider, for example nvidia-prod $ nemoclaw onboard # re-run to re-enter the cleared provider ``` + + +```console +$ nemohermes credentials list # see which providers are registered +$ nemohermes credentials reset # clear a single provider, for example nvidia-prod +$ nemohermes onboard # re-run to re-enter the cleared provider +``` + -The credentials command is documented in full at [`nemoclaw credentials reset `](/reference/commands#nemoclaw-credentials-reset-provider). + +The credentials command is documented in full at [`nemoclaw credentials reset `](../reference/commands#nemoclaw-credentials-reset-provider). + + +The credentials command is documented in full in the [Commands reference](../reference/commands). + ### Rebuild a Sandbox While Preserving Workspace State + If you changed the underlying Dockerfile, upgraded OpenClaw, or want to pick up a new base image without losing your sandbox's workspace files, use `rebuild` instead of destroying and recreating: + + +If you changed the underlying Dockerfile, upgraded Hermes, or want to pick up a new base image without losing your sandbox's state files, use `rebuild` instead of destroying and recreating: + + ```console $ nemoclaw rebuild ``` + + +```console +$ nemohermes rebuild +``` + Rebuild 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. + +Refer to [`nemoclaw rebuild`](../reference/commands#nemoclaw-name-rebuild) for flag details. + + +Refer to the [Commands reference](../reference/commands) for `nemohermes rebuild` flag details. + ### Add a Network Preset After Onboarding Apply an additional preset, such as Telegram or GitHub, to a running sandbox without re-onboarding: + ```console $ nemoclaw policy-add ``` + + +```console +$ nemohermes policy-add +``` + -Refer to [`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. +See [`NEMOCLAW_POLICY_MODE`](../reference/commands#nemoclaw-onboard) for the full table. ## Update to the Maintained Version + When a maintained NemoClaw release becomes available, update the `nemoclaw` CLI on your host and check existing sandboxes for stale agent/runtime versions. + + +When a maintained NemoClaw release becomes available, update the `nemohermes` CLI on your host and check existing sandboxes for stale agent/runtime versions. + The standard installer follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes. ### Update the NemoClaw CLI Re-run the installer. -Before it onboards anything, the installer calls [`nemoclaw backup-all`](/reference/commands#nemoclaw-backup-all) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. + +Before it onboards anything, the installer calls [`nemoclaw backup-all`](../reference/commands#nemoclaw-backup-all) automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. + + +Before it onboards anything, the installer calls `nemohermes backup-all` automatically, storing a snapshot of each running sandbox in `~/.nemoclaw/rebuild-backups/` as a safety net. + If your existing gateway is from OpenShell earlier than `0.0.37`, the installer prompts before it runs the new automatic gateway upgrade path. + The automatic path is offered only when the existing `nemoclaw` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway. For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemoclaw backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. + + +The automatic path is offered only when the existing `nemohermes` CLI supports `backup-all`; older installs must preserve sandbox state manually before retiring the gateway. +For unattended installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1`, or manually run `nemohermes backup-all`, `openshell gateway remove nemoclaw || openshell gateway destroy -g nemoclaw || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), and `sudo pkill -f openshell-gateway` if a privileged host gateway remains before rerunning the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. + ```console $ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash @@ -198,49 +377,99 @@ $ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash ### Upgrade Sandboxes with Stale Agent and Runtime Versions + The installer checks registered sandboxes after onboarding succeeds and runs `nemoclaw upgrade-sandboxes --auto` for stale running sandboxes. + + +The installer checks registered sandboxes after onboarding succeeds and runs `nemohermes upgrade-sandboxes --auto` for stale running sandboxes. + Use `upgrade-sandboxes` directly to verify the result, rebuild when you skipped the installer or onboarding step, or handle sandboxes that were stopped or could not be version-checked. The upgrade flow is non-destructive by default because NemoClaw preserves manifest-defined workspace state, but a manual snapshot before any major upgrade gives you a state restore point. + ```console $ nemoclaw snapshot create --name pre-upgrade # optional, recommended $ nemoclaw update --yes # updates CLI through the maintained installer flow $ nemoclaw upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes $ nemoclaw upgrade-sandboxes # manually rebuild remaining stale running sandboxes ``` + + +```console +$ nemohermes snapshot create --name pre-upgrade # optional, recommended +$ nemohermes update --yes # updates CLI through the maintained installer flow +$ nemohermes upgrade-sandboxes --check # verify or list remaining stale/unknown sandboxes +$ nemohermes upgrade-sandboxes # manually rebuild remaining stale running sandboxes +``` + + `nemoclaw update` is the CLI wrapper around the same installer path as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash`. Use `nemoclaw update --check` when you only want to inspect version state and see the maintained update command. + + +`nemohermes update` is the CLI wrapper around the same installer path with Hermes selected. +Use `nemohermes update --check` when you only want to inspect version state and see the maintained update command. + + For scripted manual rebuilds, use `nemoclaw upgrade-sandboxes --auto` to skip the confirmation prompt. + + +For scripted manual rebuilds, use `nemohermes upgrade-sandboxes --auto` to skip the confirmation prompt. + If the upgraded sandbox needs its workspace state reverted, restore the pre-upgrade snapshot into the running sandbox. This restores saved state directories only; it does not downgrade the sandbox image or agent/runtime: + ```console $ nemoclaw snapshot restore pre-upgrade ``` + + +```console +$ nemohermes snapshot restore pre-upgrade +``` + ### What Changes During a Rebuild Each rebuild destroys the existing container and creates a new one. -NemoClaw protects your data through the same backup-and-restore flow as [`nemoclaw rebuild`](/reference/commands#nemoclaw-name-rebuild): + +NemoClaw protects your data through the same backup-and-restore flow as [`nemoclaw rebuild`](../reference/commands#nemoclaw-name-rebuild): - NemoClaw preserves manifest-defined workspace state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the agent manifest, typically `/sandbox/.openclaw/workspace/`; for Hermes this also includes `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. - NemoClaw does not preserve runtime changes outside the workspace state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-workspace paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemoclaw onboard --from` or a manual `openshell sandbox download` before the rebuild starts. + + +NemoClaw protects your data through the same backup-and-restore flow as `nemohermes rebuild`: + +- NemoClaw preserves manifest-defined Hermes state. Before deleting the old container, NemoClaw snapshots the state directories and durable state files defined in the Hermes manifest, including `SOUL.md` and the SQLite database behind `.hermes/state.db`. Stored credentials (`~/.nemoclaw/credentials.json`) and registered policy presets live on the host and are re-applied to the new sandbox automatically. +- NemoClaw does not preserve runtime changes outside the manifest-defined state directories. This includes packages installed inside the running container with `apt` or `pip`, files in non-state paths, and in-memory or process state. If you have customized the running container at runtime, capture that as `Dockerfile` changes for `nemohermes onboard --from` or a manual `openshell sandbox download` before the rebuild starts. + Aborts before the destroy step are non-destructive. The flow refuses to proceed past preflight if a credential is missing or past backup if required manifest-defined state cannot be copied, so a failed run leaves the original sandbox intact and ready to retry. When a backup command reports partial archive output, NemoClaw keeps the usable entries and reports only the manifest-defined paths that could not be archived. -See [Backup and Restore](/manage-sandboxes/backup-restore) for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough. +See [Backup and Restore](backup-restore) for the full list of state-preservation guarantees, snapshot retention, and instructions for manual backups when the auto-flow is not enough. + The rebuild preflight reads the provider credential recorded by your last `nemoclaw onboard` session. If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight may still reference the old key and fail before any destroy step runs. To recover, re-run `nemoclaw onboard` and select your current provider. This refreshes the session metadata. + + +The rebuild preflight reads the provider credential recorded by your last `nemohermes onboard` session. +If you have switched providers since onboarding, for example from a remote API to a local Ollama setup, the preflight may still reference the old key and fail before any destroy step runs. + +To recover, re-run `nemohermes onboard` and select your current provider. +This refreshes the session metadata. + Your existing container keeps serving traffic until the new image is ready. @@ -248,9 +477,16 @@ Your existing container keeps serving traffic until the new image is ready. To remove NemoClaw and all resources created during setup, run the CLI's built-in uninstall command: + ```bash nemoclaw uninstall ``` + + +```bash +nemohermes uninstall +``` + | Flag | Effect | |--------------------|------------------------------------------------------| @@ -259,16 +495,16 @@ nemoclaw uninstall | `--delete-models` | Also remove NemoClaw-pulled Ollama models. | -`nemoclaw uninstall` preserves `~/.nemoclaw/rebuild-backups/` (host-side snapshots that `nemoclaw snapshot create` and `nemoclaw backup-all` 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 that snapshot and `backup-all` commands write), `~/.nemoclaw/backups/` (workspace backups that `scripts/backup-workspace.sh` writes), and `~/.nemoclaw/sandboxes.json` (the sandbox registry) by default. Uninstall removes every other entry under `~/.nemoclaw/`. Interactive runs prompt before they remove the preserved entries; the default answer keeps them. For non-interactive runs (`--yes`, `NEMOCLAW_NON_INTERACTIVE=1`, or a non-TTY shell), set `NEMOCLAW_UNINSTALL_DESTROY_USER_DATA=1` to acknowledge data loss and remove the preserved entries as well. -See [`nemoclaw uninstall`](/reference/commands#nemoclaw-uninstall) for the full preservation contract. +See the [Commands reference](../reference/commands#nemoclaw-uninstall) for the full preservation contract. -`nemoclaw uninstall` runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. +The CLI uninstall command runs the version-pinned `uninstall.sh` that shipped with your installed CLI, so it does not fetch anything over the network at uninstall time. -If the `nemoclaw` CLI is missing or broken, fall back to the hosted script: +If the CLI is missing or broken, fall back to the hosted script: ```bash curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash @@ -280,11 +516,11 @@ The same `--yes`, `--keep-openshell`, and `--delete-models` flags listed above a curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -s -- --yes --delete-models ``` -For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, see [`nemoclaw uninstall` vs. the hosted `uninstall.sh`](/reference/commands#nemoclaw-uninstall-vs-the-hosted-uninstallsh). +For a full comparison of the two forms, including what they fetch, what they trust, and when to prefer each, see [`nemoclaw uninstall` vs. the hosted `uninstall.sh`](../reference/commands#nemoclaw-uninstall-vs-the-hosted-uninstallsh). ## Related Topics -- [Set Up Messaging Channels](/manage-sandboxes/messaging-channels) to connect Telegram, Discord, or Slack. -- [Workspace Files](/manage-sandboxes/workspace-files) for persistent OpenClaw files inside the sandbox. -- [Backup and Restore](/manage-sandboxes/backup-restore) for snapshot and restore workflows. -- [Monitor Sandbox Activity](/monitoring/monitor-sandbox-activity) for observability tools. +- [Set Up Messaging Channels](messaging-channels) to connect Telegram, Discord, or Slack. +- [Workspace Files](workspace-files) for persistent OpenClaw files inside the sandbox. +- [Backup and Restore](backup-restore) for snapshot and restore workflows. +- [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) for observability tools. diff --git a/docs/manage-sandboxes/messaging-channels.mdx b/docs/manage-sandboxes/messaging-channels.mdx index 8404b38029..8ff68656a5 100644 --- a/docs/manage-sandboxes/messaging-channels.mdx +++ b/docs/manage-sandboxes/messaging-channels.mdx @@ -11,6 +11,8 @@ content: skill: priority: 30 --- +import { AgentOnly } from "../_components/AgentGuide"; + Telegram, Discord, Slack, WeChat, and WhatsApp reach your OpenClaw or Hermes agent through OpenShell-managed processes and gateway constructs. For token-based channels, NemoClaw registers credentials with OpenShell providers. WeChat captures a token through a host-side QR scan during onboarding. @@ -23,21 +25,44 @@ Both rely on QR-based pairing flows that are more fragile than token-based bots, Interfaces, defaults, and supported features may change, and these channels are not recommended for production use. + You can enable channels during `nemoclaw onboard` or add them later with host-side `nemoclaw channels` commands. -Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes at image build time, and changes inside the running container do not persist across rebuilds. - +Do not run agent-specific channel mutation commands such as `openclaw channels add` or `openclaw channels remove` inside the sandbox because NemoClaw generates `/sandbox/.openclaw/openclaw.json` at image build time, and changes inside the running container do not persist across rebuilds. + + +You can enable channels during `nemohermes onboard` or add them later with host-side `nemohermes channels` commands. +Do not mutate messaging configuration directly inside the sandbox because NemoClaw generates `/sandbox/.hermes/.env` and Hermes config at image build time, and changes inside the running container do not persist across rebuilds. + + + `nemoclaw tunnel start` does not start Telegram, Discord, Slack, or other chat bridges. It only starts optional host services such as the cloudflared tunnel when that binary is present. (`nemoclaw start` is kept as a deprecated alias.) -For details, refer to [Commands](/reference/commands). + + +`nemohermes 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). ## Prerequisites + + - A machine where you can run `nemoclaw onboard` (local or remote host that runs the gateway and sandbox). + + + + +- A machine where you can run `nemohermes onboard` (local or remote host that runs the gateway and sandbox). + + - A token for each token-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 + + | Channel | Required tokens | Optional settings | |---------|-----------------|-------------------| | Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | @@ -46,6 +71,19 @@ For details, refer to [Commands](/reference/commands). | WeChat (experimental) | None. Captured via host-side QR scan during `nemoclaw onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | | WhatsApp (experimental) | None. Pair via QR after rebuild | None | + + + +| Channel | Required tokens | Optional settings | +|---------|-----------------|-------------------| +| Telegram | `TELEGRAM_BOT_TOKEN` | `TELEGRAM_ALLOWED_IDS` for DM allowlisting, `TELEGRAM_REQUIRE_MENTION` for group-chat replies | +| Discord | `DISCORD_BOT_TOKEN` | `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION` | +| Slack | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `SLACK_ALLOWED_USERS` for DM and channel `@mention` user allowlisting, `SLACK_ALLOWED_CHANNELS` for channel ID allowlisting | +| WeChat (experimental) | None. Captured via host-side QR scan during `nemohermes onboard` | `WECHAT_ALLOWED_IDS` for DM allowlisting | +| WhatsApp (experimental) | None. Pair via QR after rebuild | None | + + + Telegram uses a bot token from [BotFather](https://t.me/BotFather). Open Telegram, send `/newbot` to [@BotFather](https://t.me/BotFather), follow the prompts, and copy the token. For Telegram group chats, disable privacy mode before testing group replies: in @BotFather, run `/setprivacy`, choose the bot, then choose **Disable**. @@ -74,7 +112,12 @@ WeChat (experimental) delivers messages over Tencent's iLink gateway via the ups The supported mode in this release is **personal WeChat** (`bot_type=3`). WeChat Official Account and WeCom/Enterprise WeChat are not wired up. + Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemoclaw onboard`. + + +Because the bot token only exists after a successful iLink QR handshake, NemoClaw runs the QR login on the host during `nemohermes onboard`. + You scan the QR with WeChat on your phone (Discover → Scan), confirm the login, and NemoClaw captures the token, `accountId`, `baseUrl`, and `userId` from the iLink response. NemoClaw registers the token as the `-wechat-bridge` OpenShell provider and substitutes the `openshell:resolve:env:WECHAT_BOT_TOKEN` placeholder for it inside the sandbox, so the token never lands in the image or on disk inside the running container. The non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) is baked into the sandbox image so the in-sandbox bridge can pre-seed the per-account context tokens without re-running the QR handshake. @@ -134,13 +177,25 @@ $ export SLACK_ALLOWED_CHANNELS= ``` This release does not support non-interactive WeChat configuration because the iLink QR handshake requires a human to scan the QR on a paired phone. + Run `nemoclaw onboard` interactively when you want to enable WeChat. + + +Run `nemohermes onboard` interactively when you want to enable WeChat. + Then run onboarding: + ```console $ nemoclaw onboard ``` + + +```console +$ nemohermes onboard +``` + Complete the rest of the wizard so the blueprint can create OpenShell providers where needed (for example `-telegram-bridge` or `-wechat-bridge`), bake channel configuration into the image (`NEMOCLAW_MESSAGING_CHANNELS_B64`), and start the sandbox. @@ -149,12 +204,20 @@ Complete the rest of the wizard so the blueprint can create OpenShell providers Run channel commands from the host, not from inside the sandbox. Use `channels list` to see the supported channel names: + ```console $ nemoclaw my-assistant channels list ``` + + +```console +$ nemohermes my-assistant channels list +``` + Add the channel you want: + ```console $ nemoclaw my-assistant channels add telegram $ nemoclaw my-assistant channels add discord @@ -162,13 +225,28 @@ $ nemoclaw my-assistant channels add slack $ nemoclaw my-assistant channels add wechat $ nemoclaw my-assistant channels add whatsapp ``` + + +```console +$ nemohermes my-assistant channels add telegram +$ nemohermes my-assistant channels add discord +$ nemohermes my-assistant channels add slack +$ nemohermes my-assistant channels add wechat +$ nemohermes my-assistant channels add whatsapp +``` + `channels add` collects whatever each channel needs. It prompts for Telegram, Discord, and Slack tokens, runs an interactive host-side QR scan for WeChat, and collects nothing for WhatsApp because pairing happens in-sandbox after rebuild. It registers bridge providers with the OpenShell gateway when tokens were captured, records the channel in the sandbox registry, and asks whether to rebuild immediately. The command accepts mixed-case input such as `Telegram`, then stores and prints the canonical lowercase channel name. If a matching built-in network policy preset exists, `channels add` applies it to the sandbox automatically before the rebuild so the bridge has egress to its upstream API. + If applying the preset fails, NemoClaw warns and tells you to re-apply manually with `nemoclaw policy-add ` after the rebuild. + + +If applying the preset fails, NemoClaw warns and tells you to re-apply manually with `nemohermes policy-add ` after the rebuild. + Choose the rebuild so the running sandbox image picks up the new channel. For Telegram, Discord, and Slack, `channels add` also checks the rebuilt runtime for the selected bridge and reports startup, credential, or missing-plugin warnings before returning. If you need optional channel settings such as `TELEGRAM_ALLOWED_IDS`, `TELEGRAM_REQUIRE_MENTION`, `DISCORD_SERVER_ID`, `DISCORD_USER_ID`, `DISCORD_REQUIRE_MENTION`, `SLACK_ALLOWED_USERS`, or `SLACK_ALLOWED_CHANNELS`, export them before the rebuild starts. @@ -176,27 +254,53 @@ Telegram Bot API `sendMessage` calls prove outbound delivery from the bot; to te For a repeatable live Telegram reply check, run `test/e2e/test-messaging-providers.sh` with `TELEGRAM_BOT_TOKEN_REAL`, `TELEGRAM_AUTHORIZED_CHAT_IDS` or `TELEGRAM_CHAT_ID`, and `NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E=1`. If you defer the rebuild, apply the change later: + ```console $ nemoclaw my-assistant rebuild ``` + + +```console +$ nemohermes my-assistant rebuild +``` + In non-interactive mode, set the required environment variables before running `channels add`. Missing credentials fail fast, and the command queues the change for a manual rebuild: + ```console $ NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ nemoclaw my-assistant channels add telegram $ nemoclaw my-assistant rebuild ``` + + +```console +$ NEMOCLAW_NON_INTERACTIVE=1 TELEGRAM_BOT_TOKEN= \ + nemohermes my-assistant channels add telegram +$ nemohermes my-assistant rebuild +``` + For Discord server access after onboarding, include the server settings when you add the channel and rebuild: + ```console $ DISCORD_BOT_TOKEN= \ DISCORD_SERVER_ID= \ DISCORD_REQUIRE_MENTION=1 \ nemoclaw my-assistant channels add discord ``` + + +```console +$ DISCORD_BOT_TOKEN= \ + DISCORD_SERVER_ID= \ + DISCORD_REQUIRE_MENTION=1 \ + nemohermes my-assistant channels add discord +``` + ### `channels add wechat` @@ -210,9 +314,16 @@ Keep the terminal in the foreground until you see `✓ WeChat login confirmed`. Second, the command requires an interactive terminal. Non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`) fails fast with a clear error because the QR handshake needs a paired phone. + ```console $ nemoclaw my-assistant channels add wechat ``` + + +```console +$ nemohermes my-assistant channels add wechat +``` + If `WECHAT_BOT_TOKEN` is already cached for this sandbox (the operator onboarded with WeChat earlier), `channels add wechat` reuses the cached token and skips the QR scan to keep the upstream plugin's existing iLink session intact. Re-running QR would invalidate that session. @@ -227,10 +338,18 @@ Rebuild the sandbox after the update so the image reflects the current channel s To remove a channel and clear its stored credentials, run: + ```console $ nemoclaw my-assistant channels remove telegram $ nemoclaw my-assistant channels remove wechat ``` + + +```console +$ nemohermes my-assistant channels remove telegram +$ nemohermes my-assistant channels remove wechat +``` + `channels remove wechat` clears the bot token, deletes the `-wechat-bridge` OpenShell provider, and drops `wechat` from the sandbox's enabled-channel set. The next rebuild produces an image without the WeChat channel block in `openclaw.json` and without the per-account state files under `/sandbox/.openclaw/openclaw-weixin/`. @@ -247,6 +366,7 @@ Removing the entry from the phone is recommended if you plan to re-pair the same Use `channels stop` when you want to pause a bridge without deleting credentials: + ```console $ nemoclaw my-assistant channels stop telegram $ nemoclaw my-assistant channels start telegram @@ -254,8 +374,23 @@ $ nemoclaw my-assistant channels start telegram $ nemoclaw my-assistant channels stop wechat $ nemoclaw my-assistant channels start wechat ``` + + +```console +$ nemohermes my-assistant channels stop telegram +$ nemohermes my-assistant channels start telegram + +$ nemohermes my-assistant channels stop wechat +$ nemohermes my-assistant channels start wechat +``` + + For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.openclaw/openclaw-weixin/accounts/` intact even though the bridge is no longer wired up in `openclaw.json`. + + +For WeChat specifically, `channels stop wechat` followed by a rebuild keeps the per-account state files under `/sandbox/.hermes/` intact even though the bridge is no longer wired up in Hermes config. + A subsequent `channels start wechat` plus rebuild revives the bridge against the same iLink account without a fresh QR scan. The bot token is held by the OpenShell provider across the stop/start cycle. @@ -267,33 +402,60 @@ Running two sandboxes against the same WeChat account causes one of them to lose If you enable a messaging channel and another sandbox already uses the same token, onboarding prompts you to confirm before continuing in interactive mode and exits non-zero in non-interactive mode. If NemoClaw only has legacy channel metadata and cannot compare credential hashes, it keeps the conservative warning. Re-run `channels add ` with the intended token to refresh the stored non-secret hash. + `nemoclaw status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. + + +`nemohermes status` reports cross-sandbox overlaps so you can resolve duplicates before messages start dropping. + ## Stop Messaging Delivery Use `channels stop` when you want to pause one bridge and keep the sandbox running. + Use `nemoclaw tunnel stop` or its deprecated alias `nemoclaw stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the OpenClaw gateway inside the selected sandbox. + + +Use `nemohermes tunnel stop` when you want to stop host auxiliary services and also ask NemoClaw to stop the Hermes gateway inside the selected sandbox. + Stopping the in-sandbox gateway stops Telegram, Discord, Slack, WeChat, and WhatsApp polling for that sandbox until you restart the sandbox or gateway. ## Confirm Delivery After the sandbox is running, send a message to the configured bot or app. If delivery fails, use `openshell term` on the host, check gateway logs, and verify network policy allows the channel API. -Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`) or review [Common Integration Policy Examples](/network-policy/integration-policy-examples). +Use the matching policy preset (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`) or review [Common Integration Policy Examples](../network-policy/integration-policy-examples). ## Tunnel Command + When the host has `cloudflared`, `nemoclaw tunnel start` starts a cloudflared tunnel that can expose the dashboard with a public URL. + + +When the host has `cloudflared`, `nemohermes tunnel start` starts a cloudflared tunnel that can expose the forwarded Hermes endpoint with a public URL. + Set `CLOUDFLARE_TUNNEL_TOKEN` before running the command when you want to use a Cloudflare named tunnel instead of a generated quick-tunnel URL. + `nemoclaw tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. The older `nemoclaw start` still works as a deprecated alias. + + +`nemohermes tunnel stop` stops the tunnel and asks NemoClaw to stop the in-sandbox gateway for the selected or default sandbox. + + ```console $ nemoclaw tunnel start ``` + + +```console +$ nemohermes tunnel start +``` + ## Related Topics -- [Deploy NemoClaw to a Remote GPU Instance](/deployment/deploy-to-remote-gpu) for remote deployment with messaging. -- [Architecture](/reference/architecture) for how providers, the gateway, and the sandbox fit together. -- [Commands](/reference/commands) for `channels add`, `channels remove`, `channels start`, `channels stop`, `tunnel start`, `tunnel stop`, and `status`. +- [Deploy NemoClaw to a Remote GPU Instance](../deployment/deploy-to-remote-gpu) for remote deployment with messaging. +- [Architecture](../reference/architecture) for how providers, the gateway, and the sandbox fit together. +- [Commands](../reference/commands) for `channels add`, `channels remove`, `channels start`, `channels stop`, `tunnel start`, `tunnel stop`, and `status`. diff --git a/docs/manage-sandboxes/runtime-controls.mdx b/docs/manage-sandboxes/runtime-controls.mdx index 177dd987d0..8a43fbe296 100644 --- a/docs/manage-sandboxes/runtime-controls.mdx +++ b/docs/manage-sandboxes/runtime-controls.mdx @@ -11,6 +11,8 @@ content: skill: priority: 10 --- +import { AgentOnly } from "../_components/AgentGuide"; + This page explains which parts of a running NemoClaw sandbox can change immediately and which changes require a rebuild or re-onboard. ## What you can change at runtime @@ -18,6 +20,8 @@ This page explains which parts of a running NemoClaw sandbox can change immediat NemoClaw applies its security posture in three layers — what is baked into the sandbox image at onboard, what is hot-reloadable on the running sandbox, and what requires a rebuild or re-onboard. The table below maps each commonly changed item to the layer that owns it and the command that changes it. + + | Item | When the change takes effect | How to change it | |---|---|---| | Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Rebuild required (`openclaw.json` is locked at sandbox creation) | `nemoclaw rebuild` after picking a different provider via `nemoclaw inference set` | @@ -38,13 +42,52 @@ The table below maps each commonly changed item to the layer that owns it and th If a row above conflicts with what you observe, the runtime source of truth inside the sandbox is `/opt/nemoclaw/openclaw.json`; the host registry caches metadata but the image and OpenClaw read from the in-sandbox file. + + + +| Item | When the change takes effect | How to change it | +|---|---|---| +| Inference provider (cloud, NVIDIA Endpoints, local Ollama / vLLM, compatible-endpoint, …) | Runtime route changes apply immediately; rebuild if you need to rebake model metadata into the image | `nemohermes inference set` for route changes, or `nemohermes rebuild` after changing build-time settings | +| Inference model on the current provider | Hot-reloadable through the Hermes config sync path | `nemohermes inference set` | +| Agent runtime (Hermes vs OpenClaw) | Re-onboard required (the agent and its state layout are baked at onboard) | `nemohermes onboard --recreate-sandbox` or `nemoclaw onboard --agent openclaw --recreate-sandbox` | +| Network policy preset (slack, discord, telegram, brave, …) | Runtime — applies on the next request; rebuild only required if the preset adds bind-mounted secrets | `nemohermes policy-add ` / `policy-remove ` | +| Network allow-list (custom hosts) | Runtime — picks up at next request | `openshell policy set` or interactive approval prompt at the gateway | +| Channel tokens (Slack / Discord / Telegram bot credentials) | Rebuild required (tokens are baked into the sandbox image at onboard so they never leave the host clear-text) | `nemohermes channels add ` then accept the rebuild prompt | +| Channel enable/disable (turn a configured channel off without removing the token) | Rebuild required (`/sandbox/.hermes/.env` and Hermes config are baked at image build time) | `nemohermes channels stop ` then rebuild | +| API/dashboard forward port | Runtime — port is re-resolved on next `connect` | `nemohermes connect` or `openshell forward start` | +| Filesystem layout (Landlock zones, read-only mounts, container caps) | **Locked at creation** — no runtime change | Re-onboard with `nemohermes onboard --recreate-sandbox` | +| Sandbox name | **Locked at creation** | Re-onboard with a different `--name` | +| GPU passthrough enable / device selector | **Locked at creation** | Re-onboard with `--gpu` / `--sandbox-gpu-device` | +| Hermes `config.yaml` keys | Mixed. Inference keys can be patched by `nemohermes inference set`; image, policy, and channel changes still require rebuild. | Prefer NemoClaw host commands so the host registry and rebuilt image stay aligned | + +If a row above conflicts with what you observe, the runtime source of truth for +Hermes is `/sandbox/.hermes/config.yaml` plus `/sandbox/.hermes/.env`; the host +registry caches metadata but the image and Hermes runtime read from the +in-sandbox files. + + + ## See also The mutability table above is a consolidated index of information that lives in more detail on per-topic pages: -- [Manage Sandbox Lifecycle](/manage-sandboxes/lifecycle) — full rebuild / re-onboard / upgrade workflow. -- [Switch Inference Providers](/inference/switch-inference-providers) — the rebuild path for provider and model changes. -- [Customize Network Policy](/network-policy/customize-network-policy) and [Approve Network Requests](/network-policy/approve-network-requests) — runtime policy editing and operator approval flow. -- [Security Best Practices](/security/best-practices) — the per-attack-surface posture table that this page complements. -- [OpenClaw Security Controls](/security/openclaw-controls) — application-layer controls that operate independently of NemoClaw. -- [CLI Commands Reference](/reference/commands) — full flag surface for every `nemoclaw` command, including the env vars that affect runtime behavior. + + +- [Manage Sandbox Lifecycle](lifecycle) — full rebuild / re-onboard / upgrade workflow. +- [Switch Inference Providers](../inference/switch-inference-providers) — the rebuild path for provider and model changes. +- [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) — runtime policy editing and operator approval flow. +- [Security Best Practices](../security/best-practices) — the per-attack-surface posture table that this page complements. +- [OpenClaw Security Controls](../security/openclaw-controls) — application-layer controls that operate independently of NemoClaw. +- [CLI Commands Reference](../reference/commands) — full flag surface for every `nemoclaw` command, including the env vars that affect runtime behavior. + + + + +- [Manage Sandbox Lifecycle](lifecycle) — full rebuild / re-onboard / upgrade workflow. +- [Switch Inference Providers](../inference/switch-inference-providers) — the runtime route and rebuild paths for provider and model changes. +- [Customize Network Policy](../network-policy/customize-network-policy) and [Approve Network Requests](../network-policy/approve-network-requests) — runtime policy editing and operator approval flow. +- [Security Best Practices](../security/best-practices) — the per-attack-surface posture table that this page complements. +- [OpenClaw Controls](../security/openclaw-controls-hermes) — application-layer controls outside NemoClaw's scope for Hermes-oriented deployments. +- [CLI Commands Reference](../reference/commands) — full flag surface for every `nemohermes` and `nemoclaw` command, including the env vars that affect runtime behavior. + + diff --git a/docs/manage-sandboxes/workspace-files.mdx b/docs/manage-sandboxes/workspace-files.mdx index 5e099cb5c6..4e19253f73 100644 --- a/docs/manage-sandboxes/workspace-files.mdx +++ b/docs/manage-sandboxes/workspace-files.mdx @@ -9,6 +9,10 @@ keywords: ["nemoclaw workspace files", "soul.md", "user.md", "identity.md", "age content: type: "concept" --- +import { AgentOnly } from "../_components/AgentGuide"; + + + OpenClaw stores its personality, user context, and behavioral configuration in a set of Markdown files inside the sandbox. These files live at `/sandbox/.openclaw/workspace/` and are collectively called **workspace files**. @@ -94,7 +98,7 @@ Workspace files are removed from the sandbox unless you created a snapshot or ba Back up your workspace files before running `nemoclaw destroy`. -See [Backup and Restore](/manage-sandboxes/backup-restore) for instructions. +See [Backup and Restore](backup-restore) for instructions. ## Editing Workspace Files @@ -107,6 +111,45 @@ You can edit them in two ways: ## Next Steps -- [Set Up Task-Specific Sub-Agents](/inference/set-up-sub-agent) -- [Backup and Restore workspace files](/manage-sandboxes/backup-restore) -- [Commands reference](/reference/commands) +- [Set Up Task-Specific Sub-Agents](../inference/set-up-sub-agent) +- [Backup and Restore workspace files](backup-restore) +- [Commands reference](../reference/commands) + + + + +Hermes stores durable agent state under `/sandbox/.hermes/` instead of the OpenClaw workspace directory. +The main Hermes configuration lives in `/sandbox/.hermes/config.yaml`, environment settings live in `/sandbox/.hermes/.env`, and runtime state such as logs, memory, platform sessions, and the SQLite state database lives under the same `.hermes` tree. + +## Important Hermes State + +| Path | Purpose | +|---|---| +| `/sandbox/.hermes/config.yaml` | NemoClaw-generated Hermes runtime configuration. | +| `/sandbox/.hermes/.env` | NemoClaw-generated environment and messaging placeholders. | +| `/sandbox/.hermes/state.db` | Hermes SQLite state database. | +| `/sandbox/.hermes/platforms/` | Messaging platform state, including QR-paired sessions such as WhatsApp. | +| `/sandbox/.hermes/logs/` | Hermes runtime logs. | +| `/sandbox/SOUL.md` | Durable top-level Hermes persona file preserved by NemoClaw snapshots. | + +## Persistence Behavior + +Hermes state lives in the sandbox's persistent state volume, not only in the container image. +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`. + +Running `nemohermes destroy` deletes the sandbox and its persistent state volume. +Back up important state before destroying a Hermes sandbox. + +## Editing State + +Prefer NemoClaw host commands for generated configuration such as model, provider, messaging, and policy settings. +Direct edits to `/sandbox/.hermes/config.yaml` or `/sandbox/.hermes/.env` can be overwritten by rebuilds. +Use `nemohermes connect` when you need to inspect runtime files interactively, or use `openshell sandbox download` and `openshell sandbox upload` for manual file transfer. + +## Next Steps + +- [Backup and Restore workspace files](backup-restore) +- [Commands reference](../reference/commands) + + diff --git a/docs/monitoring/monitor-sandbox-activity.mdx b/docs/monitoring/monitor-sandbox-activity.mdx index 461210e60e..9ec7e66cb5 100644 --- a/docs/monitoring/monitor-sandbox-activity.mdx +++ b/docs/monitoring/monitor-sandbox-activity.mdx @@ -11,6 +11,8 @@ content: skill: priority: 10 --- +import { AgentOnly } from "../_components/AgentGuide"; + Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, trace agent behavior, and diagnose problems. ## Prerequisites @@ -22,11 +24,23 @@ Use the NemoClaw status, logs, and TUI tools together to inspect sandbox health, Run the status command to view the sandbox state, gateway health, and active inference configuration: + ```console $ nemoclaw status ``` + + +```console +$ nemohermes status +``` + + For local Ollama and local vLLM routes, `nemoclaw status` also probes the host-side health endpoint directly. + + +For local Ollama and local vLLM routes, `nemohermes status` also probes the host-side health endpoint directly. + This catches a stopped local backend before you retry `inference.local` from inside the sandbox. Key fields in the output include the following: @@ -36,22 +50,41 @@ Key fields in the output include the following: - Inference health for local Ollama and local vLLM, which shows `healthy` or `unreachable` together with the probed local URL. - NIM status, which shows whether a NIM container is running and healthy when that path is in use. + Run `nemoclaw status` on the host to check sandbox state. + + +Run `nemohermes status` on the host to check sandbox state. + 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: + ```console $ nemoclaw logs ``` + + +```console +$ nemohermes logs +``` + To follow the log output in real time: + ```console $ nemoclaw logs --follow ``` + + +```console +$ nemohermes logs --follow +``` + ## Monitor Network Activity in the TUI @@ -69,28 +102,49 @@ The TUI shows the following information: - 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. +Refer to [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests) for details on handling blocked requests. ## Test Inference Run a test inference request to verify that the provider is responding: + ```console $ nemoclaw my-assistant connect $ openclaw agent --agent main -m "Test inference" --session-id debug ``` + + +```console +$ nemohermes my-hermes connect +$ hermes +``` + If the request fails, check the following: + + 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. + + + +1. Run `nemohermes 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 `nemohermes logs --follow` to view error messages from the blueprint runner. +3. Verify that the inference endpoint is reachable from the host. + + + ## Related Topics -- [Troubleshooting](/reference/troubleshooting) for common issues and resolution steps. -- [Commands](/reference/commands) for the full CLI reference. -- [Approve or Deny Agent Network Requests](/network-policy/approve-network-requests) for the operator approval flow. -- [Switch Inference Providers](/inference/switch-inference-providers) to change the active provider. +- [Troubleshooting](../reference/troubleshooting) for common issues and resolution steps. +- [Commands](../reference/commands) for the full CLI reference. +- [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests) for the operator approval flow. +- [Switch Inference Providers](../inference/switch-inference-providers) to change the active provider. diff --git a/docs/network-policy/approve-network-requests.mdx b/docs/network-policy/approve-network-requests.mdx index 1fc525c64b..f5318a0a45 100644 --- a/docs/network-policy/approve-network-requests.mdx +++ b/docs/network-policy/approve-network-requests.mdx @@ -53,7 +53,7 @@ The TUI presents an approval prompt for each blocked request. 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](/network-policy/customize-network-policy). +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). ## Run the Walkthrough @@ -68,6 +68,6 @@ The walkthrough requires tmux and the `NVIDIA_API_KEY` environment variable, and ## Related Topics -- [Customize the Sandbox Network Policy](/network-policy/customize-network-policy) to add endpoints permanently. -- [Network Policies](/reference/network-policies) for the full baseline policy reference. -- [Monitor Sandbox Activity](/monitoring/monitor-sandbox-activity) for general sandbox monitoring. +- [Customize the Sandbox Network Policy](customize-network-policy) to add endpoints permanently. +- [Network Policies](../reference/network-policies) for the full baseline policy reference. +- [Monitor Sandbox Activity](../monitoring/monitor-sandbox-activity) for general sandbox monitoring. diff --git a/docs/network-policy/customize-network-policy.mdx b/docs/network-policy/customize-network-policy.mdx index ab8d2f159e..98a4db3e25 100644 --- a/docs/network-policy/customize-network-policy.mdx +++ b/docs/network-policy/customize-network-policy.mdx @@ -11,6 +11,8 @@ content: skill: priority: 10 --- +import { AgentOnly } from "../_components/AgentGuide"; + Add, remove, or modify the endpoints that the sandbox is allowed to reach. The sandbox policy is defined in a declarative YAML file in the NemoClaw repository and enforced at runtime by [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). @@ -18,9 +20,14 @@ 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`. + + +Apply a custom NemoClaw preset with `nemohermes 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). +See [Agent cannot reach a host-side HTTP service](../reference/troubleshooting#agent-cannot-reach-a-host-side-http-service). ## Prerequisites @@ -39,12 +46,22 @@ Static changes modify the baseline policy file and take effect after the next sa ### Edit the Policy File + Open `nemoclaw-blueprint/policies/openclaw-sandbox.yaml` and add or modify endpoint entries. If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into this file and re-run `nemoclaw onboard`. If you only need to apply a preset to a running sandbox, use `nemoclaw policy-add` under [Dynamic Changes](#dynamic-changes). That updates the live policy and does not edit `openclaw-sandbox.yaml`. + + +Open the Hermes policy additions and shared sandbox policy files under `agents/hermes/` and `nemoclaw-blueprint/policies/`, then add or modify endpoint entries. + +If you want a built-in preset to be part of the baseline policy, merge its `network_policies` entries into the appropriate policy file and re-run `nemohermes onboard`. + +If you only need to apply a preset to a running sandbox, use `nemohermes 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. @@ -63,9 +80,16 @@ Each entry in the `network` section defines an endpoint group with the following Apply the updated policy by re-running the onboard wizard: + ```console $ nemoclaw onboard ``` + + +```console +$ nemohermes onboard +``` + The wizard picks up the modified policy file and applies it to the sandbox. @@ -73,9 +97,16 @@ The wizard picks up the modified policy file and applies it to the sandbox. Check that the sandbox is running with the updated policy: + ```console $ nemoclaw status ``` + + +```console +$ nemohermes status +``` + ### Add Blueprint Policy Additions @@ -89,7 +120,7 @@ Dynamic changes apply a policy update to a running sandbox without restarting it > [!WARNING] > `openshell policy set` **replaces** the sandbox's live policy with the contents of the file you provide; it does not merge. -> A running sandbox's live policy is the baseline from `openclaw-sandbox.yaml` plus every preset that was layered on during onboarding. +> A running sandbox's live policy is the baseline policy plus every preset that was layered on during onboarding. > Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect. ### Option 1: Drop a Preset File and Use `policy-add` (Recommended) @@ -119,18 +150,29 @@ This is the non-destructive path and the only flow NemoClaw supports out of the 2. Apply it to the running sandbox: - ```console - $ nemoclaw my-assistant policy-add - ``` + + +```console +$ nemoclaw my-assistant policy-add +``` + + + + +```console +$ nemohermes my-assistant policy-add +``` - NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. - Existing presets and the baseline remain in place. - The preset file under `presets/` also persists across sandbox recreations. + + +NemoClaw reads the live policy via `openshell policy get --full`, structurally merges your preset's `network_policies` into it, and writes the merged result back. +Existing presets and the baseline remain in place. +The preset file under `presets/` also persists across sandbox recreations. ### Option 2: Snapshot, Edit, and Set via OpenShell Use this path only when you cannot add a file under the NemoClaw source tree. -You must start from the **live** policy, not from `openclaw-sandbox.yaml`, so the presets layered on at onboarding are preserved in the file you apply. +You must start from the **live** policy, not from a baseline policy file, so the presets layered on at onboarding are preserved in the file you apply. ```console $ openshell policy get --full my-assistant > live-policy.yaml @@ -145,8 +187,13 @@ $ openshell policy set --policy live-policy.yaml my-assistant ### Scope of Dynamic Changes Dynamic changes apply only to the current session. -When the sandbox stops, the running policy resets to the baseline composed from `openclaw-sandbox.yaml` plus the presets recorded for the sandbox. +When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox. + To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above — the file under `presets/` persists) or edit `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. + + +To make a custom policy survive a sandbox recreation, ship the preset file in the repository (Option 1 above — the file under `presets/` persists) or edit the Hermes policy additions and re-run `nemohermes onboard`. + ### Approve Requests Interactively @@ -162,9 +209,9 @@ This is useful when you want to test a destination before deciding whether it be 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](/network-policy/integration-policy-examples). +For guided post-install examples, see [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. +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. Available presets: @@ -189,9 +236,16 @@ Available presets: To apply a preset to a running sandbox: + ```console $ nemoclaw policy-add ``` + + +```console +$ nemohermes policy-add +``` + Preset selection is interactive when you omit a preset name. @@ -200,35 +254,72 @@ Pass a preset name with `--yes` for scripted workflows. For example, to interactively add PyPI access to a running sandbox: + ```console $ nemoclaw my-assistant policy-add ``` + + +```console +$ nemohermes my-assistant policy-add +``` + To list which presets are applied to a sandbox: + ```console $ nemoclaw policy-list ``` + + +```console +$ nemohermes policy-list +``` + + To include a preset in the baseline, merge its entries into `openclaw-sandbox.yaml` and re-run `nemoclaw onboard`. + + +To include a preset in the baseline, merge its entries into the Hermes policy additions and re-run `nemohermes onboard`. + The `openshell policy set --policy ` command operates on raw policy files and does not -accept the `preset:` metadata block used in preset YAML files. Use `nemoclaw policy-add` for -presets. +accept the `preset:` metadata block used in preset YAML files. + +Use `nemoclaw policy-add` for presets. + + +Use `nemohermes policy-add` for presets. + For scripted workflows, `policy-add` and `policy-remove` accept the preset name as a positional argument: + ```console $ nemoclaw my-assistant policy-add pypi --yes $ nemoclaw my-assistant policy-remove pypi --yes ``` + + +```console +$ nemohermes my-assistant policy-add pypi --yes +$ nemohermes 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. +See [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. + + +`nemohermes rebuild` reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication. + ## Custom Preset Files @@ -261,17 +352,31 @@ Rename `preset.name` if NemoClaw refuses to apply the file because of a collisio ### Apply a Single File + ```console $ nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml ``` + + +```console +$ nemohermes my-assistant policy-add --from-file ./presets/my-internal-api.yaml +``` + Preview the endpoints without applying with `--dry-run`, and skip the confirmation prompt with `--yes` or by exporting `NEMOCLAW_NON_INTERACTIVE=1`. ### Apply Every File in a Directory + ```console $ nemoclaw my-assistant policy-add --from-dir ./presets/ --yes ``` + + +```console +$ nemohermes 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. @@ -286,16 +391,28 @@ Review every host in a custom preset before applying it, especially when the fil Custom presets applied with `--from-file` or `--from-dir` are recorded in the NemoClaw sandbox registry alongside their full YAML content, so they can be removed by name — the original file does not need to be kept on disk: + ```console $ nemoclaw my-assistant policy-remove my-internal-api --yes ``` + + +```console +$ nemohermes 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 `nemohermes policy-list` to see every preset currently applied to the sandbox. + ## Related Topics -- [Approve or Deny Agent Network Requests](/network-policy/approve-network-requests) for real-time operator approval. -- [Common Integration Policy Examples](/network-policy/integration-policy-examples) for maintained preset examples such as Outlook, messaging, GitHub, Jira, Brave Search, package managers, Hugging Face, and local inference. -- [Network Policies](/reference/network-policies) for the full baseline policy reference. +- [Approve or Deny Agent Network Requests](approve-network-requests) for real-time operator approval. +- [Common Integration Policy Examples](integration-policy-examples) for maintained preset examples such as Outlook, messaging, GitHub, Jira, Brave Search, package managers, Hugging Face, and local inference. +- [Network Policies](../reference/network-policies) for the full baseline policy reference. - OpenShell [Policy Schema](https://docs.nvidia.com/openshell/latest/reference/policy-schema.html) for the full YAML policy schema reference. - OpenShell [Sandbox Policies](https://docs.nvidia.com/openshell/latest/sandboxes/policies.html) for applying, iterating, and debugging policies at the OpenShell layer. diff --git a/docs/network-policy/integration-policy-examples.mdx b/docs/network-policy/integration-policy-examples.mdx index f74ceb5106..b40e13e504 100644 --- a/docs/network-policy/integration-policy-examples.mdx +++ b/docs/network-policy/integration-policy-examples.mdx @@ -11,6 +11,8 @@ content: skill: priority: 15 --- +import { AgentOnly } from "../_components/AgentGuide"; + {/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */} {/* SPDX-License-Identifier: Apache-2.0 */} @@ -33,9 +35,16 @@ Replace `my-assistant` with your sandbox name in the examples. Check the current policy state first: + ```console $ nemoclaw my-assistant policy-list ``` + + +```console +$ nemohermes my-assistant policy-list +``` + For a live view of blocked requests, open the OpenShell TUI in a separate host terminal: @@ -71,31 +80,60 @@ NemoClaw ships maintained policy presets for common services in `nemoclaw-bluepr Preview the endpoints before applying: + ```console $ nemoclaw my-assistant policy-add outlook --dry-run ``` + + +```console +$ nemohermes my-assistant policy-add outlook --dry-run +``` + Apply the preset: + ```console $ nemoclaw my-assistant policy-add outlook --yes ``` + + +```console +$ nemohermes my-assistant policy-add outlook --yes +``` + Remove it later if the sandbox no longer needs that access: + ```console $ nemoclaw my-assistant policy-remove outlook --yes ``` + + +```console +$ nemohermes 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. + ```console $ nemoclaw my-assistant policy-add outlook --dry-run $ nemoclaw my-assistant policy-add outlook --yes ``` + + +```console +$ nemohermes my-assistant policy-add outlook --dry-run +$ nemohermes my-assistant policy-add outlook --yes +``` + Then configure the email or calendar tool credentials through the integration you are running in the sandbox. Keep OAuth client secrets and refresh tokens out of policy files. @@ -108,18 +146,35 @@ If the blocked endpoint is not covered by the maintained `outlook` preset, treat Telegram needs both channel configuration and egress policy. If you already enabled Telegram during onboarding but did not include the preset, add it to the running sandbox: + ```console $ nemoclaw my-assistant policy-add telegram --yes ``` + + +```console +$ nemohermes my-assistant policy-add telegram --yes +``` + To add Telegram after onboarding, set the token on the host, add the channel, rebuild so the image picks up the channel config, and make sure the policy preset is applied: + ```console $ export TELEGRAM_BOT_TOKEN= $ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add telegram $ nemoclaw my-assistant rebuild $ nemoclaw my-assistant policy-add telegram --yes ``` + + +```console +$ export TELEGRAM_BOT_TOKEN= +$ NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add telegram +$ nemohermes my-assistant rebuild +$ nemohermes my-assistant policy-add telegram --yes +``` + If delivery fails, open the TUI and send a test message to the bot: @@ -136,6 +191,7 @@ Use the matching policy preset after you configure the channel credentials. For Slack: + ```console $ export SLACK_BOT_TOKEN= $ export SLACK_APP_TOKEN= @@ -143,9 +199,20 @@ $ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add slack $ nemoclaw my-assistant rebuild $ nemoclaw my-assistant policy-add slack --yes ``` + + +```console +$ export SLACK_BOT_TOKEN= +$ export SLACK_APP_TOKEN= +$ NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add slack +$ nemohermes my-assistant rebuild +$ nemohermes my-assistant policy-add slack --yes +``` + For Discord: + ```console $ export DISCORD_BOT_TOKEN= $ export DISCORD_SERVER_ID= @@ -153,13 +220,31 @@ $ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add discord $ nemoclaw my-assistant rebuild $ nemoclaw my-assistant policy-add discord --yes ``` + + +```console +$ export DISCORD_BOT_TOKEN= +$ export DISCORD_SERVER_ID= +$ NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add discord +$ nemohermes my-assistant rebuild +$ nemohermes my-assistant policy-add discord --yes +``` + If you enabled Slack or Discord during onboarding, apply only the matching preset: + ```console $ nemoclaw my-assistant policy-add slack --yes $ nemoclaw my-assistant policy-add discord --yes ``` + + +```console +$ nemohermes my-assistant policy-add slack --yes +$ nemohermes my-assistant policy-add discord --yes +``` + ## WeChat or WhatsApp Messaging (Experimental) @@ -170,27 +255,53 @@ WeChat uses Tencent's iLink Bot API for personal accounts. The bot token is captured by a host-side QR scan during onboarding rather than pasted from a developer portal. Add the channel interactively and apply the preset: + ```console $ nemoclaw my-assistant channels add wechat $ nemoclaw my-assistant rebuild $ nemoclaw my-assistant policy-add wechat --yes ``` + + +```console +$ nemohermes my-assistant channels add wechat +$ nemohermes my-assistant rebuild +$ nemohermes my-assistant policy-add wechat --yes +``` + WhatsApp Web pairs entirely inside the sandbox via QR scan, so `channels add` does not collect a host-side token. Apply the preset and complete the in-sandbox pairing after the rebuild: + ```console $ NEMOCLAW_NON_INTERACTIVE=1 nemoclaw my-assistant channels add whatsapp $ nemoclaw my-assistant rebuild $ nemoclaw my-assistant policy-add whatsapp --yes ``` + + +```console +$ NEMOCLAW_NON_INTERACTIVE=1 nemohermes my-assistant channels add whatsapp +$ nemohermes my-assistant rebuild +$ nemohermes my-assistant policy-add whatsapp --yes +``` + If you enabled WeChat or WhatsApp during onboarding, apply only the matching preset: + ```console $ nemoclaw my-assistant policy-add wechat --yes $ nemoclaw my-assistant policy-add whatsapp --yes ``` + + +```console +$ nemohermes my-assistant policy-add wechat --yes +$ nemohermes my-assistant policy-add whatsapp --yes +``` + ## GitHub and Jira @@ -199,17 +310,33 @@ Use `jira` when the agent needs Atlassian Jira access. Preview first: + ```console $ nemoclaw my-assistant policy-add github --dry-run $ nemoclaw my-assistant policy-add jira --dry-run ``` + + +```console +$ nemohermes my-assistant policy-add github --dry-run +$ nemohermes my-assistant policy-add jira --dry-run +``` + Apply the preset that matches the workflow: + ```console $ nemoclaw my-assistant policy-add github --yes $ nemoclaw my-assistant policy-add jira --yes ``` + + +```console +$ nemohermes my-assistant policy-add github --yes +$ nemohermes 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`. @@ -228,20 +355,36 @@ This manual probe proves curl reached Atlassian, but no Jira credentials were su Remove access when the task is done: + ```console $ nemoclaw my-assistant policy-remove github --yes $ nemoclaw my-assistant policy-remove jira --yes ``` + + +```console +$ nemohermes my-assistant policy-remove github --yes +$ nemohermes my-assistant policy-remove jira --yes +``` + ## Brave Search The default Balanced policy tier includes `brave`. If you chose Restricted during onboarding or removed the preset later, add it before enabling Brave Search workflows: + ```console $ nemoclaw my-assistant policy-add brave --dry-run $ nemoclaw my-assistant policy-add brave --yes ``` + + +```console +$ nemohermes my-assistant policy-add brave --dry-run +$ nemohermes my-assistant policy-add brave --yes +``` + The Brave Search API key is still configured separately during onboarding or through the web search setup flow. @@ -258,21 +401,41 @@ Use these presets when an agent workflow installs packages or downloads model as Add only the preset required for the task: + ```console $ nemoclaw my-assistant policy-add npm --yes $ nemoclaw my-assistant policy-add pypi --yes $ nemoclaw my-assistant policy-add brew --yes $ nemoclaw my-assistant policy-add huggingface --yes ``` + + +```console +$ nemohermes my-assistant policy-add npm --yes +$ nemohermes my-assistant policy-add pypi --yes +$ nemohermes my-assistant policy-add brew --yes +$ nemohermes my-assistant policy-add huggingface --yes +``` + Remove package access after a one-time setup task if the sandbox no longer needs it: + ```console $ nemoclaw my-assistant policy-remove npm --yes $ nemoclaw my-assistant policy-remove pypi --yes $ nemoclaw my-assistant policy-remove brew --yes $ nemoclaw my-assistant policy-remove huggingface --yes ``` + + +```console +$ nemohermes my-assistant policy-remove npm --yes +$ nemohermes my-assistant policy-remove pypi --yes +$ nemohermes my-assistant policy-remove brew --yes +$ nemohermes my-assistant policy-remove huggingface --yes +``` + The `pypi` preset allows Python, `pip`, virtual-environment Python and `pip`, and `/usr/local/bin/uv` to reach PyPI endpoints. If `uv` is installed somewhere else in the sandbox, add a custom preset for that binary path instead of broadening the maintained preset locally. @@ -283,16 +446,27 @@ The sandbox base image includes Homebrew (Linuxbrew), so applying the `brew` pre A `/usr/local/bin/brew` wrapper puts the entry point on the sandbox `PATH` while delegating to the Linuxbrew prefix. Installed formula commands are available from the Linuxbrew bin directory in sandbox shell sessions: + ```console $ nemoclaw my-assistant policy-add brew --yes $ nemoclaw my-assistant exec -- brew install $ nemoclaw my-assistant exec -- bash -lc '' ``` + + +```console +$ nemohermes my-assistant policy-add brew --yes +$ nemohermes my-assistant exec -- brew install +$ nemohermes my-assistant exec -- bash -lc '' +``` + You do not need to bootstrap Homebrew, install build dependencies, or source `brew shellenv` inside the sandbox. ## Model Pricing + + OpenClaw's gateway fetches reference pricing from LiteLLM and OpenRouter on every start so it can populate `usage.cost` in session JSONL records. 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. @@ -308,30 +482,59 @@ $ nemoclaw my-assistant policy-add openclaw-pricing --yes After the next gateway restart the WARN entries stop and `usage.cost` populates from the fetched pricing tables. + + + +Hermes does not use OpenClaw's model-pricing reference fetch. + + + ## Local Inference Use `local-inference` when the sandbox needs access to host-side local inference services such as Ollama or vLLM through the OpenShell host gateway. Onboarding auto-suggests this preset when you choose a local provider. If you need to add it after onboarding: + ```console $ nemoclaw my-assistant policy-add local-inference --dry-run $ nemoclaw my-assistant policy-add local-inference --yes ``` + + +```console +$ nemohermes my-assistant policy-add local-inference --dry-run +$ nemohermes my-assistant policy-add local-inference --yes +``` + Then verify the sandbox status: + ```console $ nemoclaw my-assistant status ``` + + +```console +$ nemohermes my-assistant status +``` + ## Inspect or Replace the Live Policy Use `policy-list` for normal preset state: + ```console $ nemoclaw my-assistant policy-list ``` + + +```console +$ nemohermes my-assistant policy-list +``` + Use OpenShell when you need the full enforced YAML: @@ -347,11 +550,16 @@ $ openshell policy set --policy live-policy.yaml my-assistant --wait `openshell policy set` replaces the live policy with the file you provide. It does not accept a preset file that starts with a `preset:` block, and it does not merge a single endpoint into the existing policy. + Use `nemoclaw my-assistant policy-add` for maintained NemoClaw presets. + + +Use `nemohermes my-assistant policy-add` for maintained NemoClaw presets. + ## Next Steps -- [Approve or Deny Agent Network Requests](/network-policy/approve-network-requests) for the interactive OpenShell TUI flow. -- [Customize the Sandbox Network Policy](/network-policy/customize-network-policy) for static policy edits and raw OpenShell policy files. -- [Messaging Channels](/manage-sandboxes/messaging-channels) for Telegram, Discord, Slack, WeChat, and WhatsApp channel configuration. -- [Commands](/reference/commands) for the full `policy-add`, `policy-list`, `policy-remove`, and `channels` command reference. +- [Approve or Deny Agent Network Requests](approve-network-requests) for the interactive OpenShell TUI flow. +- [Customize the Sandbox Network Policy](customize-network-policy) for static policy edits and raw OpenShell policy files. +- [Messaging Channels](../manage-sandboxes/messaging-channels) for Telegram, Discord, Slack, WeChat, and WhatsApp channel configuration. +- [Commands](../reference/commands) for the full `policy-add`, `policy-list`, `policy-remove`, and `channels` command reference. diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index 91067b2c3a..27da70afe9 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -233,13 +233,13 @@ The router selects from the configured pool, then calls the upstream NVIDIA endp Some model and provider combinations need agent-specific compatibility setup. NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so OpenClaw and Hermes fixes can be tested and reviewed independently. -Refer to [Inference Options](/inference/inference-options) for provider configuration details. +Refer to [Inference Options](../inference/inference-options) for provider configuration details. ## 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. -See [Credential Storage](/security/credential-storage) for the inspection, rotation, and migration flow. +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 afcd9b6de5..9a6261334e 100644 --- a/docs/reference/cli-selection-guide.mdx +++ b/docs/reference/cli-selection-guide.mdx @@ -1,8 +1,8 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "CLI Selection Guide" -sidebar-title: "CLI Selection Guide" +title: "Choose Between NemoClaw and OpenShell CLIs" +sidebar-title: "Which CLI to Use" description: "Choose between the NemoClaw CLI and the OpenShell CLI for common sandbox operations." description-agent: "Explains when to use `nemoclaw` versus `openshell` for NemoClaw-managed sandboxes, including lifecycle, inference, policy, monitoring, file transfer, and gateway operations." keywords: ["nemoclaw vs openshell", "which cli", "nemoclaw cli", "openshell cli", "sandbox commands"] @@ -205,8 +205,8 @@ Use `openshell sandbox upload` and `openshell sandbox download` for manual file ## Related Topics -- [Commands](/reference/commands) for the full NemoClaw command reference. -- [Manage Sandbox Lifecycle](/manage-sandboxes/lifecycle) for day-two operations. -- [Switch Inference Models](/inference/switch-inference-providers) for inference route examples. -- [Customize the Network Policy](/network-policy/customize-network-policy) for persistent network access changes. -- [Approve or Deny Network Requests](/network-policy/approve-network-requests) for the OpenShell TUI approval flow. +- [Commands](commands) for the full NemoClaw command reference. +- [Manage Sandbox Lifecycle](../manage-sandboxes/lifecycle) for day-two operations. +- [Switch Inference Models](../inference/switch-inference-providers) for inference route examples. +- [Customize the Network Policy](../network-policy/customize-network-policy) for persistent network access changes. +- [Approve or Deny Network Requests](../network-policy/approve-network-requests) for the OpenShell TUI approval flow. diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 55787f2ecc..92bc094168 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -11,7 +11,7 @@ content: --- 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](/reference/cli-selection-guide). +For guidance on when to use `nemoclaw` versus the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). ## `/nemoclaw` Slash Command @@ -98,7 +98,7 @@ To perform those steps manually, run `nemoclaw backup-all`, retire the old gatew 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. See [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. @@ -112,7 +112,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](/reference/network-policies#policy-tiers). +For details on tiers and the presets each includes, see [Network Policies](network-policies#policy-tiers). In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`): @@ -561,8 +561,8 @@ 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). +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). If you want to upgrade the sandbox while preserving state, use `nemoclaw rebuild` instead. @@ -821,7 +821,7 @@ $ nemoclaw my-assistant skill install ./my-skill/ The skill directory must contain a `SKILL.md` file with YAML frontmatter that includes a `name` field. Skill names must contain only alphanumeric characters, dots, hyphens, and underscores. -OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](/deployment/install-openclaw-plugins). +OpenClaw plugins are a different kind of extension. To install an OpenClaw plugin, see [Install OpenClaw Plugins](../deployment/install-openclaw-plugins). Run `nemoclaw skill install --help` to print usage for this subcommand. If you pass a plugin-shaped directory to `skill install`, the CLI prints a plugin-specific hint instead of treating it as a missing skill file. @@ -1278,7 +1278,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 (see [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.). diff --git a/docs/reference/network-policies.mdx b/docs/reference/network-policies.mdx index 34eb9882a4..665fd55aa0 100644 --- a/docs/reference/network-policies.mdx +++ b/docs/reference/network-policies.mdx @@ -48,12 +48,12 @@ 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). +See [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. WeChat and WhatsApp are experimental. -Review [Messaging Channels](/manage-sandboxes/messaging-channels) before enabling them. +Review [Messaging Channels](../manage-sandboxes/messaging-channels) before enabling them. diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx index b89ebeac30..31235107c1 100644 --- a/docs/reference/troubleshooting.mdx +++ b/docs/reference/troubleshooting.mdx @@ -223,7 +223,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](/reference/commands#environment-variables) for the full list of port overrides. +See [Environment Variables](commands#environment-variables) for the full list of port overrides. ### Running multiple sandboxes simultaneously @@ -571,7 +571,7 @@ Follow these steps to reconnect. If the sandbox remains missing after restarting the gateway, run `nemoclaw onboard` to recreate it. The wizard prompts for confirmation before destroying an existing sandbox. If you confirm, it **destroys and recreates** the sandbox. Workspace files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md, and daily memory notes) are lost. -Back up your workspace first by following the instructions at [Back Up and Restore](/manage-sandboxes/backup-restore). +Back up your workspace first by following the instructions at [Back Up and Restore](../manage-sandboxes/backup-restore). ### Sandbox is running an outdated agent version @@ -748,7 +748,7 @@ This is expected behavior. Changing or exporting it later does not rewrite the baked `openclaw.json` inside an existing sandbox. If you need a different device-auth setting, rerun onboarding so NemoClaw rebuilds the sandbox image with the desired configuration. -For the security trade-offs, refer to [Security Best Practices](/security/best-practices). +For the security trade-offs, refer to [Security Best Practices](../security/best-practices). ### `openclaw.json` is empty after changing inference @@ -782,7 +782,7 @@ $ nemoclaw channels remove Both offer to rebuild the sandbox so the image reflects the new channel set. In non-interactive mode (`NEMOCLAW_NON_INTERACTIVE=1`), the commands stage the change and leave the rebuild to a follow-up `nemoclaw rebuild`. WeChat and WhatsApp are experimental. -Review [Messaging Channels](/manage-sandboxes/messaging-channels) before enabling them. +Review [Messaging Channels](../manage-sandboxes/messaging-channels) before enabling them. WeChat captures its bot token through a host-side QR scan during `nemoclaw onboard` or `channels add wechat`. You scan the iLink QR from WeChat on your phone and NemoClaw registers the captured token with the OpenShell gateway. @@ -1057,7 +1057,7 @@ $ openshell term ``` To permanently allow an endpoint, add it to the network policy. -Refer to [Customize the Network Policy](/network-policy/customize-network-policy) for details. +Refer to [Customize the Network Policy](../network-policy/customize-network-policy) for details. ### Dashboard not reachable after setting a custom port @@ -1278,7 +1278,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/windows-preparation). +For environment setup steps, see [Windows Prerequisites](../get-started/windows-preparation). ### `wsl --install --no-distribution` returns Forbidden (403) @@ -1352,7 +1352,7 @@ $ sudo systemctl stop ollama $ OLLAMA_CONTEXT_LENGTH=16384 ollama serve ``` -For additional troubleshooting, see the [Quickstart](/get-started/quickstart) and [Windows Setup](/get-started/windows-preparation) pages. +For additional troubleshooting, see the [Quickstart](../get-started/quickstart) and [Windows Setup](../get-started/windows-preparation) pages. ## Podman @@ -1362,7 +1362,7 @@ If you encounter issues with Podman, switch to a tested runtime (Docker Engine, ## Brev -For Brev setup instructions, refer to [Brev Web UI](/deployment/brev-web-ui). +For Brev setup instructions, refer to [Brev Web UI](../deployment/brev-web-ui). ### Most OpenClaw skills show as blocked @@ -1404,7 +1404,7 @@ If you see this error, use the host-side config command instead: $ nemoclaw config set --key --value '' --restart ``` -Refer to [Commands](/reference/commands) for the full list of supported configuration keys. +Refer to [Commands](commands) for the full list of supported configuration keys. ### OpenClaw dashboard is unreachable after extended uptime on Brev diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx index 778642761e..f64a601ad7 100644 --- a/docs/security/best-practices.mdx +++ b/docs/security/best-practices.mdx @@ -9,11 +9,13 @@ keywords: ["nemoclaw security best practices", "sandbox security controls risk f content: type: "concept" --- +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw ships with deny-by-default security controls across four layers: network, filesystem, process, and inference. You can tune every control, but each change shifts the risk profile. This page documents every configurable knob, its default, what it protects, the concrete risk of relaxing it, and a recommendation for common use cases. -For background on how the layers fit together, refer to [How It Works](/about/how-it-works). +For background on how the layers fit together, refer to [How It Works](../about/how-it-works). {/* TODO: uncomment after the OpenShell docs are published @@ -28,11 +30,11 @@ NemoClaw enforces security at four layers. NemoClaw locks some when it creates the sandbox and requires a restart to change them. You can hot-reload others while the sandbox runs. -The following diagram shows the default posture immediately after `nemoclaw onboard`, before you approve any endpoints or apply any presets. +The following diagram shows the default posture immediately after onboarding, before you approve any endpoints or apply any presets. ```mermaid flowchart TB - subgraph HOST["Your Machine: default posture after nemoclaw onboard"] + subgraph HOST["Your Machine: default posture after onboarding"] direction TB YOU["👤 Operator"] @@ -84,7 +86,7 @@ flowchart TB | Network | Unauthorized outbound connections and data exfiltration. | OpenShell gateway | Yes. Use `openshell policy set` or operator approval. | | Filesystem | System binary tampering, credential theft, config manipulation. | Landlock LSM + container mounts | Landlock layout: no. Requires sandbox re-creation. Use host-side NemoClaw commands for durable config changes. | | Process | Privilege escalation, fork bombs, syscall abuse. | Container runtime (Docker/K8s `securityContext`) | No. Requires sandbox re-creation. | -| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use `nemoclaw inference set`. | +| Inference | Credential exposure, unauthorized model access, cost overruns. | OpenShell gateway | Yes. Use the NemoClaw inference switching command. | ## Network Controls @@ -95,7 +97,7 @@ See the [Network Controls](https://docs.nvidia.com/openshell/latest/security/bes ### Deny-by-Default Egress -The sandbox blocks all outbound connections unless you explicitly list the endpoint in the policy file `nemoclaw-blueprint/policies/openclaw-sandbox.yaml`. +The sandbox blocks all outbound connections unless you explicitly list the endpoint in the applicable baseline policy files. | Aspect | Detail | |---|---| @@ -148,7 +150,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 (for example, by running `nemoclaw onboard`), the policy resets to the baseline defined in the blueprint. | +| What you can change | The system merges approved endpoints into the sandbox's policy as a new durable revision. They persist across sandbox restarts within the same sandbox instance. However, when you destroy and recreate the sandbox through onboarding, the policy resets to the baseline defined in the blueprint. | | Risk if relaxed | Approving an endpoint permanently widens the running sandbox's policy. If you approve a broad domain (such as a CDN that hosts arbitrary content), the agent can fetch anything from that domain until you destroy and recreate the sandbox. | | Recommendation | Review each blocked request before approving. If you find yourself approving the same endpoint repeatedly, add it to the baseline policy with appropriate binary and path restrictions. To reset approved endpoints, destroy and recreate the sandbox. | @@ -193,6 +195,8 @@ The container mounts system directories read-only to prevent the agent from modi ### Agent Config Directory + + The `/sandbox/.openclaw` directory contains the OpenClaw gateway configuration (model routing, CORS settings, channel config). The current entrypoint reads the gateway auth token from OpenClaw config when present, exports it as `OPENCLAW_GATEWAY_TOKEN`, and writes it to `/tmp/nemoclaw-proxy-env.sh` so interactive sandbox sessions can reach the gateway through system-wide shell hooks. In root mode, the gateway process still runs as the separate `gateway` user, but the token is intentionally available to sandbox shells for local gateway access. @@ -229,6 +233,25 @@ If any high-risk state-dir root is a symlink when the lock runs, it refuses to p | Risk of default | A writable `.openclaw` directory lets the agent modify its own gateway config: disabling CORS or redirecting inference to an attacker-controlled endpoint. | | Recommendation | For always-on assistants handling sensitive workloads, lock config after initial setup. For development workflows, the writable default is appropriate. | + + + +The `/sandbox/.hermes` directory contains Hermes runtime configuration, generated environment settings, logs, platform state, and durable database state. +NemoClaw writes `config.yaml` and `.env` during onboarding and rebuilds. +Direct edits to these files can be overwritten when NemoClaw regenerates the image. + +Hermes also stores runtime state such as `state.db`, logs, and platform sessions under the `.hermes` tree. +Messaging sessions such as WhatsApp pairing can remain mutable by design so they survive rebuilds. + +| Aspect | Detail | +|---|---| +| Default | The Hermes config tree contains NemoClaw-generated config plus mutable runtime state. | +| What you can change | Use host-side NemoClaw commands for durable model, provider, messaging, and policy changes; inspect files directly only for debugging. | +| Risk of direct edits | Direct edits to generated config can drift from the host registry and may be lost on rebuild. | +| Recommendation | For sensitive workloads, keep generated config under NemoClaw control and back up Hermes state before destructive operations. | + + + ### Writable Paths The agent has read-write access to `/sandbox`, `/tmp`, and `/dev/null`. @@ -269,18 +292,18 @@ During `setpriv` step-down, the child process also loses `cap_setuid`, `cap_setg This is best-effort: if `capsh` is not available or `CAP_SETPCAP` is not in the bounding set, the entrypoint logs a warning and continues with the default capability set. If `setpriv` is unavailable, the entrypoint falls back to `gosu` and logs a warning that the remaining bounding-set capabilities were retained for the child process. -For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose (see [Sandbox Hardening](/deployment/sandbox-hardening)). +For additional protection, pass `--cap-drop=ALL` with `docker run` or Compose (see [Sandbox Hardening](../deployment/sandbox-hardening)). | Aspect | Detail | |---|---| | Default | The entrypoint drops dangerous capabilities at startup using `capsh`, then uses `setpriv` during user step-down when possible. Best-effort. | -| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw flow (with `nemoclaw onboard`), the entrypoint handles capability dropping automatically. | +| What you can change | When launching with `docker run` directly, pass `--cap-drop=ALL --cap-add=NET_BIND_SERVICE` for stricter enforcement. In the standard NemoClaw onboarding flow, the entrypoint handles capability dropping automatically. | | Risk if relaxed | `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` expand kernel and process attack surface. `CAP_NET_RAW` allows raw socket access for network sniffing. `CAP_DAC_OVERRIDE` bypasses filesystem permission checks. If `capsh` or `setpriv` cannot run, the container retains more of the runtime-provided capability set. | | Recommendation | Run on an image that includes `capsh` and `setpriv` (the NemoClaw image includes them). For defense-in-depth, also pass `--cap-drop=ALL` at the container runtime level. | ### Gateway Process Isolation -The OpenClaw gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent. +The in-sandbox gateway runs as a separate `gateway` user, not as the `sandbox` user that runs the agent. | Aspect | Detail | |---|---| @@ -357,7 +380,7 @@ A registry compromise or accidental force-push cannot silently swap the sandbox | Default | `nemoclaw-blueprint/blueprint.yaml` pins the sandbox image by digest. A CI regression test blocks any mutable-tag reference from merging. | | What you can change | Contributors bumping the sandbox image must update the digest in `blueprint.yaml`. Release tooling should rewrite the digest automatically. | | Risk if relaxed | Reverting to a mutable tag (`:latest`) allows a registry-side change to replace the sandbox image without any blueprint update, which is a supply-chain risk. | -| Recommendation | Always reference the sandbox image by digest. If you build a custom image with `nemoclaw onboard --from`, the digest constraint does not apply to your local build. | +| Recommendation | Always reference the sandbox image by digest. If you build a custom image with the onboarding `--from` path, the digest constraint does not apply to your local build. | ### Auth Profile Permissions @@ -373,6 +396,8 @@ This prevents other users on the host from reading stored credentials. ## Gateway Authentication Controls + + The OpenClaw gateway authenticates devices that connect to the Control UI dashboard. NemoClaw hardens these defaults at image build time. @@ -420,6 +445,15 @@ The auto-pair watcher automatically approves device pairing requests from recogn | Risk if relaxed | Approving all device types without validation lets rogue or unexpected clients pair with the gateway unchallenged. | | Recommendation | No action needed. The entrypoint handles this automatically. If you see `[auto-pair] rejected unknown client=...` in the logs, investigate the source of the unexpected connection. | + + + +Hermes exposes an OpenAI-compatible API on the forwarded Hermes port and can optionally expose the native Hermes dashboard. +Do not publish those endpoints on shared or public networks unless you put them behind your own access controls. +NemoClaw still keeps provider credentials in OpenShell and routes model traffic through `inference.local`. + + + ### CLI Secret Redaction The CLI automatically redacts secret patterns (API keys, bearer tokens, provider credentials) from command output and error messages before logging them. @@ -429,10 +463,12 @@ The CLI automatically redacts secret patterns (API keys, bearer tokens, provider | Default | Enabled. The runner redacts secrets from stdout, stderr, and thrown error messages. | | What you can change | This is not a user-facing knob. The CLI enforces it on all command output paths. | | Risk if relaxed | Without redaction, secrets could appear in terminal scrollback, log files, or debug output shared in bug reports. | -| Recommendation | No action needed. If you share `nemoclaw debug` output, verify that no secrets appear in the collected diagnostics. | +| Recommendation | No action needed. If you share NemoClaw debug output, verify that no secrets appear in the collected diagnostics. | ### Memory Secret Scanner + + The NemoClaw plugin blocks the agent from writing likely secrets (API keys, tokens, private keys) into persistent memory files. The scanner intercepts Write, Edit, and similar tool calls targeting memory and workspace paths before they reach disk. @@ -444,6 +480,14 @@ The scanner intercepts Write, Edit, and similar tool calls targeting memory and | Risk if relaxed | Without scanning, the agent could persist API keys or tokens in memory files that survive across sessions and backups. | | Recommendation | No action needed. If a write is blocked, the agent receives an actionable error listing the detected patterns. | + + + +Hermes does not use the OpenClaw NemoClaw plugin memory scanner. +Keep secrets in environment variables or OpenShell providers, and avoid writing raw credentials to Hermes state files or workspace content. + + + ## Inference Controls OpenShell routes all inference traffic through the gateway to isolate provider credentials from the sandbox. @@ -482,7 +526,7 @@ The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and ge | Aspect | Detail | |---|---| | Default | Local NVIDIA NIM and generic Linux managed vLLM install/start are hidden. DGX Spark and DGX Station managed vLLM entries, plus already-running vLLM on `localhost:8000`, are offered when detected. | -| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before running `nemoclaw onboard` to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. | +| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before onboarding to surface Local NIM and generic Linux managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. | | Risk if selected | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. The managed vLLM path pulls a container image and starts it on a supported NVIDIA GPU host. Misconfiguration can cause failed inference or unexpected behavior. | | Recommendation | Use experimental providers only for evaluation. Do not rely on them for always-on assistants. | @@ -528,7 +572,7 @@ The following patterns weaken security without providing meaningful benefit. | Omitting `protocol: rest` on REST API endpoints without a compatibility reason | Endpoints without a `protocol` field use L4-only enforcement. The proxy allows the TCP stream through after checking host, port, and binary, but cannot see or filter individual HTTP requests. | Add `protocol: rest` with explicit `rules` to enable per-request method and path control on REST APIs. Use L4 pass-through only for documented cases such as npm/Yarn on Node 22, where the client requires a CONNECT tunnel that L7 inspection would break. | | Adding endpoints to the baseline policy for one-off requests | Adding an endpoint to the baseline policy makes it permanently reachable across all sandbox instances. | Use operator approval. Approved endpoints persist within the sandbox instance but reset when you destroy and recreate the sandbox. | | Relying solely on the entrypoint for capability drops | The entrypoint drops dangerous capabilities using `capsh`, but this is best-effort. If `capsh` is unavailable or `CAP_SETPCAP` is not in the bounding set, the container runs with the default capability set. | Pass `--cap-drop=ALL` at the container runtime level as defense-in-depth. | -| Leaving `/sandbox/.openclaw` writable on sensitive workloads | This directory contains the OpenClaw gateway configuration. A writable `.openclaw` lets the agent disable CORS, redirect inference routing, or weaken gateway protections. | Lock config for always-on assistants handling sensitive data. | +| Leaving generated agent config writable on sensitive workloads | The generated config tree contains model routing, channel settings, and runtime integration state (`/sandbox/.openclaw` for OpenClaw, `/sandbox/.hermes` for Hermes). Writable config lets the agent drift from host-managed policy and routing. | Keep generated config under NemoClaw control for always-on assistants handling sensitive data. | | Adding inference provider hosts to the network policy | Direct network access to an inference host bypasses credential isolation and usage tracking. | Use OpenShell inference routing instead of adding hosts like `api.openai.com` or `api.anthropic.com` to the network policy. | | Disabling device auth for remote deployments | Without device auth, any device on the network can connect to the gateway without pairing. Combined with a cloudflared tunnel, this makes the dashboard publicly accessible and unauthenticated. | Keep `NEMOCLAW_DISABLE_DEVICE_AUTH` at its default (`0`). Only set it to `1` for local headless or development environments. | @@ -536,16 +580,16 @@ The following patterns weaken security without providing meaningful benefit. | Limitation | Impact | Mitigation | |-----------|--------|------------| -| `openclaw agent --local` bypasses gateway | Secret scanning, network policy, and inference auth are not enforced when the agent runs in local mode. | A runtime warning is emitted when `--local` is detected. Avoid `--local` for production workflows. A future OpenClaw-level hook will close this gap. | -| Direct filesystem writes bypass secret scanner | The scanner intercepts OpenClaw tool calls, not raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. The scanner is application-layer defense-in-depth, not a filesystem-level control. | +| Bypassing managed gateway paths | Network policy and inference auth are not enforced when an agent runtime is launched outside the NemoClaw-managed gateway path. | Use NemoClaw-managed sandbox entrypoints for production workflows. | +| Direct filesystem writes bypass application-layer scanners | Application-layer scanners can intercept agent tool calls, not arbitrary raw filesystem writes (e.g., `echo secret > file`). | Landlock restricts writable paths. Application-layer scanning is defense-in-depth, not a filesystem-level control. | | Base64/hex-encoded secrets are not detected | Content-based regex scanning cannot detect encoded or obfuscated secrets. | Use environment variables or credential stores instead of writing secrets to files. | ## Related Topics -- [Network Policies](/reference/network-policies) for the full baseline policy reference. -- [Customize the Network Policy](/network-policy/customize-network-policy) for static and dynamic policy changes. -- [Approve or Deny Network Requests](/network-policy/approve-network-requests) for the operator approval flow. -- [Sandbox Hardening](/deployment/sandbox-hardening) for container-level security measures. -- [Inference Options](/inference/inference-options) for provider configuration details. -- [How It Works](/about/how-it-works) for the protection layer architecture. +- [Network Policies](../reference/network-policies) for the full baseline policy reference. +- [Customize the Network Policy](../network-policy/customize-network-policy) for static and dynamic policy changes. +- [Approve or Deny Network Requests](../network-policy/approve-network-requests) for the operator approval flow. +- [Sandbox Hardening](../deployment/sandbox-hardening) for container-level security measures. +- [Inference Options](../inference/inference-options) for provider configuration details. +- [How It Works](../about/how-it-works) for the protection layer architecture. {/* - OpenShell [Security Best Practices](https://docs.nvidia.com/openshell/latest/security/best-practices.html) for the platform-level controls reference, including network namespace isolation, seccomp filters, SSRF protection, TLS termination, and gateway authentication. */} diff --git a/docs/security/credential-storage.mdx b/docs/security/credential-storage.mdx index e44057d83e..4ec2db4733 100644 --- a/docs/security/credential-storage.mdx +++ b/docs/security/credential-storage.mdx @@ -9,13 +9,25 @@ keywords: ["nemoclaw credential storage", "openshell provider", "api key securit content: type: "reference" --- +import { AgentOnly } from "../_components/AgentGuide"; + NemoClaw does not persist provider credentials to host disk. The OpenShell gateway is the only system of record for stored credentials. + When you provide a provider credential — interactively during `nemoclaw onboard` or via an environment variable — NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. + + +When you provide a provider credential — interactively during `nemohermes onboard` or via an environment variable — NemoClaw holds the value in memory only long enough to register it with the OpenShell gateway through `openshell provider create` or `openshell provider update`. + The gateway stores the credential and the OpenShell L7 proxy substitutes it into outbound requests at egress, so sandboxed agents see placeholders instead of the raw secret. + The sandbox-side OpenClaw gateway token is generated at container startup and is not rotated through provider credential commands. + + +Hermes API credentials and provider credentials are managed through the same OpenShell provider boundary; generated Hermes runtime files are recreated during rebuilds. + ## Where Credentials Live @@ -28,9 +40,16 @@ $ openshell provider list Or, equivalently, through NemoClaw: + ```console $ nemoclaw credentials list ``` + + +```console +$ nemohermes credentials list +``` + Both surface the provider names that the gateway holds credentials for. The values themselves cannot be read back from the CLI; this is a deliberate property of OpenShell. @@ -42,10 +61,21 @@ That directory is created with mode `0700` and contains no credential material. 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: + + - Prefix any command with the credential to override the gateway-stored value: `NVIDIA_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_API_KEY=nvapi-... nemohermes 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 + + + ## Deploy Reads from Environment Only `nemoclaw deploy` (which provisions a remote Brev box) cannot read secrets back from the gateway, so it requires every credential to be present in the host environment at invocation time. @@ -76,7 +106,12 @@ Run `gh auth login` if you want a persistent backing store (whichever one applie ## Migration From Earlier Releases Earlier NemoClaw releases stored credentials as plaintext JSON in `~/.nemoclaw/credentials.json` with mode `0600`. + On first `nemoclaw onboard` after upgrading, NemoClaw automatically: + + +On first `nemohermes onboard` after upgrading, NemoClaw automatically: + 1. Reads the legacy file. 2. Stages allowlisted credential values into `process.env` for the rest of the run. @@ -85,23 +120,47 @@ On first `nemoclaw onboard` after upgrading, NemoClaw automatically: You will 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. + + +If `~/.nemoclaw/credentials.json` remains after a rebuild or other credential lookup, run `nemohermes 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: + ```console $ NVIDIA_API_KEY=nvapi-new-value nemoclaw onboard ``` + + +```console +$ NVIDIA_API_KEY=nvapi-new-value nemohermes onboard +``` + To remove a credential from the gateway entirely: + ```console $ nemoclaw credentials reset ``` + + +```console +$ nemohermes credentials reset +``` + + `` is the OpenShell provider name (run `nemoclaw credentials list` first if you are not sure). + + +`` is the OpenShell provider name (run `nemohermes credentials list` first if you are not sure). + On the next run NemoClaw prompts again unless the credential is supplied through the environment. ## Security Recommendations @@ -114,4 +173,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](/security/best-practices) and [Architecture](/reference/architecture). +For the broader sandbox security model and operational trade-offs, see [Security Best Practices](best-practices) and [Architecture](../reference/architecture). diff --git a/docs/security/hermes-controls.mdx b/docs/security/hermes-controls.mdx new file mode 100644 index 0000000000..3587e70589 --- /dev/null +++ b/docs/security/hermes-controls.mdx @@ -0,0 +1,12 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "OpenClaw Security Controls Beyond NemoClaw's Scope" +sidebar-title: "OpenClaw Controls" +description: "Documents application-layer security controls that OpenClaw provides independently, where NemoClaw adds no additional protection for Hermes sandboxes." +description-agent: "Lists OpenClaw security controls that operate independently of NemoClaw in Hermes-oriented documentation. Use when reviewing the security boundary between NemoClaw, Hermes, and OpenClaw or assessing what NemoClaw does not cover." +keywords: ["openclaw security controls", "hermes security controls", "nemoclaw security boundary", "prompt injection", "tool access control"] +content: + type: "concept" +--- +TBD diff --git a/docs/security/openclaw-controls.mdx b/docs/security/openclaw-controls.mdx index c8eda7efd4..192c1860d7 100644 --- a/docs/security/openclaw-controls.mdx +++ b/docs/security/openclaw-controls.mdx @@ -124,5 +124,5 @@ The implementation detects unsafe nested quantifiers, bounds input length, and c ## Next Steps -- [Security Best Practices](/security/best-practices) for NemoClaw's own security controls and risk framework. -- [Credential Storage](/security/credential-storage) for how NemoClaw stores and protects provider credentials. +- [Security Best Practices](best-practices) for NemoClaw's own security controls and risk framework. +- [Credential Storage](credential-storage) for how NemoClaw stores and protects provider credentials. From 302d25b3370572f6afc9a0d11764097138e6ac6b Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Mon, 1 Jun 2026 18:26:08 -0700 Subject: [PATCH 03/12] docs: update landing page --- docs/index.mdx | 121 ++++++++----------------------------------------- docs/index.yml | 4 +- 2 files changed, 20 insertions(+), 105 deletions(-) diff --git a/docs/index.mdx b/docs/index.mdx index f2b6807b97..1a19c40561 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -40,7 +40,7 @@ NemoClaw also ships user skills for AI coding assistants, so tools such as Curso ## Get Started -Install NemoClaw and run the onboard wizard. +Install NemoClaw and run the onboard wizard to get started. @@ -56,135 +56,50 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +By default, NemoClaw installs the OpenClaw agent. Use one of the following quickstart guides to get started with your preferred agent. + | Agent | Guide | |-------|-------| | OpenClaw (default) | [Quickstart with OpenClaw](/user-guide/openclaw/get-started/quickstart) | | Hermes | [Quickstart with Hermes](/user-guide/hermes/get-started/quickstart-hermes) | -## Use NemoClaw User Skills +## Select User Guide for Your Agent -If you work from an AI coding assistant, load NemoClaw's user skills before you install or operate a sandbox. -The skills turn these docs into task-focused guidance that your assistant can apply to your local environment. +The NemoClaw documentation provides separate user guides for the agents it supports. Select the guide that matches your agent. You can also select the guide from the dropdown at the top of the left navigation pane. - + -Clone the skills or add them to your assistant so NemoClaw guidance is available directly in chat. +Read the OpenClaw-focused overview before launching the default sandboxed agent. -Resource +Overview - + ---- +Read the Hermes-focused overview before launching a Hermes sandboxed agent. -## Explore - -
- - - - -Learn what NemoClaw is, what capabilities it provides, and when to use it. - -Concept +Overview - - -Understand the host CLI, blueprint, sandbox lifecycle, and protection layers. - -Concept - - - - -Learn how OpenClaw, OpenShell, and NemoClaw fit together. -Learn how Hermes, OpenShell, and NemoClaw fit together. - -Concept - - - - -Track NemoClaw release changes and component version policy. - -Reference - + - +## Use NemoClaw User Skills -Install NemoClaw, verify prerequisites, and run your first sandboxed agent. +If you work from an AI coding assistant, load NemoClaw's user skills before you install or operate a sandbox. +The skills turn these docs into task-focused guidance that your assistant can apply to your local environment. -Guide - + - + -Use NemoClaw's packaged agent skills to guide coding assistants through common workflows. +Clone the skills or add them to your assistant so NemoClaw guidance is available directly in chat. Resource - - -Choose how NemoClaw routes model requests and configures inference providers. - -Guide - - - - -Create, inspect, update, and clean up NemoClaw sandboxes. - -Guide - - - - -Approve, deny, and customize sandbox network access. - -Guide - - - - -Deploy NemoClaw to remote GPU instances and manage deployment-specific setup. - -Guide - - - - -Inspect sandbox health, logs, and agent behavior during runtime. - -Guide - - - - -Review sandbox controls, credential handling, and security trade-offs. - -Guide - - - - -Look up architecture details, CLI commands, policies, and troubleshooting guidance. - -Reference - - - - -Learn about the NemoClaw architecture, plugin structure, and blueprint design in detail. - -Reference - - -
--- diff --git a/docs/index.yml b/docs/index.yml index 2f17ed81ba..ab7e5de96b 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -10,7 +10,7 @@ navigation: - tab: user-guide variants: - title: NemoClaw for OpenClaw - subtitle: Guide for the OpenClaw agent + subtitle: Guide for OpenClaw agents slug: openclaw default: true layout: @@ -167,7 +167,7 @@ navigation: - link: "Discord" href: https://discord.gg/XFpfPv9Uvx - title: NemoClaw for Hermes - subtitle: Guide for the Hermes agent + subtitle: Guide for Hermes agents slug: hermes layout: - page: "Home" From 38eae253264aeedda75ccbf1f17db94071657819 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Mon, 1 Jun 2026 19:12:37 -0700 Subject: [PATCH 04/12] test(docs): support Fern variant links --- test/check-docs-links.test.ts | 19 ++++++++++++ test/e2e/e2e-cloud-experimental/check-docs.sh | 29 ++++++++++++++----- 2 files changed, 40 insertions(+), 8 deletions(-) diff --git a/test/check-docs-links.test.ts b/test/check-docs-links.test.ts index e127c9abb5..de920133e3 100644 --- a/test/check-docs-links.test.ts +++ b/test/check-docs-links.test.ts @@ -56,6 +56,25 @@ describe("check-docs link validation", () => { expect(result.status).toBe(0); }); + it("resolves Fern user-guide variant routes in Markdown and MDX hrefs", () => { + const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-check-docs-fern-")); + const mdPath = path.join(tempDir, "guide.mdx"); + fs.writeFileSync( + mdPath, + [ + "# Guide", + "", + "[OpenClaw overview](/user-guide/openclaw/about/overview)", + '', + "", + ].join("\n"), + ); + + const result = runCheckDocs(mdPath); + + expect(result.status).toBe(0); + }); + it("ignores broken links inside tilde-fenced code blocks", () => { const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-check-docs-tildefence-")); const mdPath = path.join(tempDir, "guide.md"); diff --git a/test/e2e/e2e-cloud-experimental/check-docs.sh b/test/e2e/e2e-cloud-experimental/check-docs.sh index c720bb2fcf..26e7d05e23 100755 --- a/test/e2e/e2e-cloud-experimental/check-docs.sh +++ b/test/e2e/e2e-cloud-experimental/check-docs.sh @@ -691,6 +691,7 @@ extract_targets() { while ($visible =~ /\!?\[[^\]]*\]\(([^)\s]+)(?:\s+["'"'"'][^)"'"'"']*["'"'"'])?\)/g) { print $line . "\t" . $1 . "\n"; } while ($visible =~ /<(https?:[^>\s]+)>/g) { print $line . "\t" . $1 . "\n"; } + while ($visible =~ /\bhref=(["'"'"'])([^"'"'"'\s]+)\1/g) { print $line . "\t" . $2 . "\n"; } END { die "malformed HTML comment\n" if $in_comment; } @@ -718,14 +719,26 @@ check_local_ref() { if [[ "$stripped" == /* ]]; then local site_path="${stripped#/}" - local candidate - for candidate in \ - "$REPO_ROOT/docs/$site_path" \ - "$REPO_ROOT/docs/$site_path.mdx" \ - "$REPO_ROOT/docs/$site_path.md" \ - "$REPO_ROOT/docs/$site_path/index.mdx" \ - "$REPO_ROOT/docs/$site_path/index.md"; do - [[ -e "$candidate" ]] && return 0 + local -a site_paths=("$site_path") + case "$site_path" in + user-guide/openclaw/*) + site_paths+=("${site_path#user-guide/openclaw/}") + ;; + user-guide/hermes/*) + site_paths+=("${site_path#user-guide/hermes/}") + ;; + esac + + local route_path candidate + for route_path in "${site_paths[@]}"; do + for candidate in \ + "$REPO_ROOT/docs/$route_path" \ + "$REPO_ROOT/docs/$route_path.mdx" \ + "$REPO_ROOT/docs/$route_path.md" \ + "$REPO_ROOT/docs/$route_path/index.mdx" \ + "$REPO_ROOT/docs/$route_path/index.md"; do + [[ -e "$candidate" ]] && return 0 + done done echo "check-docs: [links] broken site route in $md_path:$line_no -> $target" >&2 return 1 From 71b50a57981e23a10276527394102423071570e3 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Mon, 1 Jun 2026 19:50:53 -0700 Subject: [PATCH 05/12] ci(docs): leave MDX link validation to Fern --- .github/workflows/docs-links-pr.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-links-pr.yaml b/.github/workflows/docs-links-pr.yaml index 5c5be2ac76..ad8f502322 100644 --- a/.github/workflows/docs-links-pr.yaml +++ b/.github/workflows/docs-links-pr.yaml @@ -9,7 +9,6 @@ on: types: [opened, reopened, synchronize] paths: - "**/*.md" - - "**/*.mdx" - ".github/workflows/docs-links-pr.yaml" - "test/e2e/e2e-cloud-experimental/check-docs.sh" @@ -34,9 +33,10 @@ jobs: base="${{ github.event.pull_request.base.sha }}" head="${{ github.event.pull_request.head.sha }}" mapfile -t doc_files < <( + # Fern preview validates MDX routes after building variant navigation. + # This raw Markdown checker only verifies repository-local .md links. git diff --name-only --diff-filter=ACMR "$base" "$head" -- \ '*.md' \ - '*.mdx' \ ':(exclude)node_modules/**' \ ':(exclude)dist/**' \ ':(exclude)vendor/**' \ From 353044c1fd59d7f64c5af6a2ce6b0d619a064d25 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Mon, 1 Jun 2026 21:48:57 -0700 Subject: [PATCH 06/12] docs: complete variants for the rest --- docs/index.yml | 2 +- docs/reference/architecture.mdx | 82 +- docs/reference/commands-nemohermes.mdx | 1498 ++++++++++++++++++++++++ docs/reference/commands.mdx | 299 ++++- package.json | 4 +- scripts/sync-agent-variant-docs.ts | 118 ++ scripts/watch-fern-preview.ts | 20 + 7 files changed, 1932 insertions(+), 91 deletions(-) create mode 100644 docs/reference/commands-nemohermes.mdx create mode 100644 scripts/sync-agent-variant-docs.ts diff --git a/docs/index.yml b/docs/index.yml index ab7e5de96b..a51af92826 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -279,7 +279,7 @@ navigation: path: reference/architecture.mdx slug: architecture - page: "CLI Commands Reference" - path: reference/commands.mdx + path: reference/commands-nemohermes.mdx slug: commands - page: "CLI Selection Guide" path: reference/cli-selection-guide.mdx diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index 27da70afe9..6fad681121 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -3,17 +3,17 @@ # SPDX-License-Identifier: Apache-2.0 title: "Architecture Details" sidebar-title: "Architecture Details" -description: "Learn how NemoClaw combines a host CLI, sandbox plugin, and versioned blueprint to move OpenClaw into a controlled sandbox." -description-agent: "Describes the NemoClaw plugin and blueprint architecture and how they orchestrate the OpenClaw sandbox. Use when looking up architecture, plugin structure, or blueprint design." -keywords: ["nemoclaw architecture", "nemoclaw plugin blueprint structure"] +description: "Learn how NemoClaw combines a host CLI, sandbox integration layer, and versioned blueprint to run compatible agents in controlled OpenShell sandboxes." +description-agent: "Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design." +keywords: ["nemoclaw architecture", "nemoclaw agent architecture", "nemoclaw plugin blueprint structure"] content: type: "reference" --- -NemoClaw combines a host CLI, a TypeScript plugin that runs with OpenClaw inside the sandbox, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell. +NemoClaw combines a host CLI, an in-sandbox integration layer, and a versioned YAML blueprint that defines the sandbox image, policies, and inference profiles applied through OpenShell. ## 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 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 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 @@ -49,8 +49,8 @@ graph LR subgraph SANDBOX["Sandbox Container 🔒"] direction TB - AGENT["Agent
OpenClaw or any
compatible agent"]:::agent - PLUG["NemoClaw Plugin
Extends agent with
managed configuration"]:::sandbox + AGENT["Compatible Agent
OpenClaw, Hermes,
or another supported runtime"]:::agent + PLUG["NemoClaw Integration
Managed configuration
and runtime context"]:::sandbox end end end @@ -98,7 +98,7 @@ graph TB subgraph DOCKER["Docker daemon"] direction TB - SANDBOX["Sandbox container 🔒
Landlock + seccomp + netns
OpenClaw agent + NemoClaw plugin"]:::sandbox + SANDBOX["Sandbox container 🔒
Landlock + seccomp + netns
Compatible agent + NemoClaw integration"]:::sandbox end end @@ -122,44 +122,33 @@ Layering from top to bottom: | Host CLI | Host process (`nemoclaw` on Node.js) | Orchestrates OpenShell via `openshell` CLI calls. | | OpenShell gateway | Host process by default; optional Linux compatibility container when the gateway binary needs a newer host ABI | Hosts the credential store, owns sandbox lifecycle coordination, and provides the L7 proxy. | | Docker daemon | Host service | Runs the Docker-driver sandbox container and, on affected Linux hosts, the optional gateway compatibility container. | -| Sandbox container | Docker container | Runs the OpenClaw agent and the NemoClaw plugin under Landlock + seccomp + netns. | +| Sandbox container | Docker container | Runs the selected compatible agent and NemoClaw integration under Landlock + seccomp + netns. | | OpenShell L7 proxy | Gateway process | Intercepts agent egress and rewrites `Authorization` headers (Bearer/Bot) and URL-path segments to inject the real credential at the network boundary. | NemoClaw never gives the sandbox a raw provider key. At onboard time it registers credentials with OpenShell's provider/placeholder system, and the L7 proxy substitutes the real value into outbound requests at egress. -The CLI helper `isInferenceRouteReady` (in `src/lib/onboard.ts`) is a host-side readiness check used by the resume flow to decide whether the active route already covers the chosen provider and model — it is not a runtime component. +The CLI helper `isInferenceRouteReady` (in `src/lib/onboard.ts`) is a host-side readiness check used by the resume flow to decide whether the active route already covers the chosen provider and model. +It is not a runtime component. For the DGX Spark-specific variant of this topology (cgroup v2, aarch64, unified memory), refer to the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). -## NemoClaw Plugin +## NemoClaw Agent Integration -The plugin is a thin TypeScript package that registers an inference provider and the `/nemoclaw` slash command. -It runs in-process with the OpenClaw gateway inside the sandbox. -It also registers runtime hooks that keep the agent aware of its environment. -Before an agent turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. +NemoClaw integrates with each supported agent through a runtime layer that adapts the agent to OpenShell-managed providers, policies, and sandbox state. +The concrete files differ by agent because each runtime has its own plugin system, config format, state layout, and startup command. + +| Agent | Integration files | Runtime behavior | +|---|---|---| +| OpenClaw | `nemoclaw/openclaw.plugin.json`, `nemoclaw/src/runtime-context.ts`, and the TypeScript package under `nemoclaw/src/` | Registers the `/nemoclaw` slash command, adds the NemoClaw inference provider, and injects sandbox and policy context into OpenClaw turns. | +| Hermes | `agents/hermes/manifest.yaml`, `agents/hermes/plugin/plugin.yaml`, `agents/hermes/generate-config.ts`, `agents/hermes/config/`, and `agents/hermes/start.sh` | Declares the Hermes agent contract, installs the NemoClaw Hermes plugin, writes `/sandbox/.hermes/config.yaml` and `/sandbox/.hermes/.env`, and launches `hermes gateway run` behind the OpenShell proxy. | + +The OpenClaw integration is a thin TypeScript plugin that runs in-process with the OpenClaw gateway inside the sandbox. +Before an OpenClaw turn starts, the plugin prepends a short context block with the active sandbox name, sandbox phase, network policy summary, and filesystem policy summary. When the policy or phase changes during a session, the plugin sends a smaller update block instead of repeating the full context. -```text -nemoclaw/ -├── src/ -│ ├── index.ts Plugin entry: registers all commands -│ ├── cli.ts Commander.js subcommand wiring -│ ├── runtime-context.ts Sandbox and policy context injection -│ ├── commands/ -│ │ ├── launch.ts Fresh install into OpenShell -│ │ ├── connect.ts Interactive shell into sandbox -│ │ ├── status.ts Blueprint run state + sandbox health -│ │ ├── logs.ts Stream blueprint and sandbox logs -│ │ └── slash.ts /nemoclaw chat command handler -│ └── blueprint/ -│ ├── resolve.ts Version resolution, cache management -│ ├── fetch.ts Download blueprint from OCI registry -│ ├── verify.ts Digest verification, compatibility checks -│ ├── exec.ts Subprocess execution of blueprint runner -│ └── state.ts Persistent state (run IDs) -├── openclaw.plugin.json Plugin manifest -└── package.json Commands declared under openclaw.extensions -``` +The Hermes integration follows the generic agent-manifest path instead of the OpenClaw plugin package path. +The manifest declares Hermes' binary, health probe, config directory, state directories, messaging support, and OpenAI-compatible API endpoint. +The build-time config generator turns NemoClaw onboarding choices into Hermes YAML and environment files, and the Hermes plugin manifest exposes NemoClaw tools and an `on_session_start` hook. ## NemoClaw Blueprint @@ -173,10 +162,13 @@ nemoclaw-blueprint/ ├── model-specific-setup/ Agent-scoped model/provider compatibility manifests ├── router/ Model Router config and routing engine ├── policies/ -│ └── openclaw-sandbox.yaml Default network + filesystem policy +│ └── openclaw-sandbox.yaml Default network + filesystem policy for the OpenClaw profile ``` -The blueprint runtime (TypeScript) lives in the plugin source tree: +Hermes keeps its agent-owned image, plugin, config, entrypoint, and policy additions under `agents/hermes/`. +The default Hermes policy starts from `agents/hermes/policy-additions.yaml`, and the permissive variant used by `shields down` lives in `agents/hermes/policy-permissive.yaml`. + +The current blueprint runner implementation lives in the `nemoclaw/` TypeScript package: ```text nemoclaw/src/blueprint/ @@ -196,8 +188,8 @@ flowchart LR D --> E[status] ``` -1. Resolve. The plugin locates the blueprint artifact and checks the version against `min_openshell_version` and `min_openclaw_version` constraints in `blueprint.yaml`. -2. Verify. The plugin checks the artifact digest against the expected value. +1. Resolve. The integration layer locates the blueprint artifact and checks the version against the OpenShell and agent runtime constraints in `blueprint.yaml`. +2. Verify. The integration layer checks the artifact digest against the expected value. 3. Plan. The runner determines what OpenShell resources to create or update, such as the gateway, providers, sandbox, inference route, and policy. 4. Apply. The runner executes the plan by calling `openshell` CLI commands. 5. Status. The runner reports current state. @@ -210,11 +202,11 @@ base image and layers the NemoClaw runtime Dockerfile on top. The direct bluepri runner still carries a pinned OpenShell Community OpenClaw image for legacy `openshell sandbox create --from` compatibility. Inside the sandbox: -- OpenClaw runs with the NemoClaw plugin pre-installed. +- 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. -- Network egress is restricted by the baseline policy in `openclaw-sandbox.yaml`. +- Network egress is restricted by the baseline policy for the selected agent profile. - Filesystem access is confined to `/sandbox` and `/tmp` for read-write access, with system paths read-only. -- The NemoClaw plugin injects sandbox and policy context into agent turns so the agent can report policy blocks accurately. +- NemoClaw injects sandbox and policy context into agent turns when the selected agent supports runtime context hooks, so the agent can report policy blocks accurately. - The image exposes a Docker health check that probes the in-sandbox gateway, so container runtimes can report whether the agent service is responding. - The image includes common runtime compatibility helpers such as Homebrew and a `python` to `python3` symlink for tools that still invoke `python`. @@ -224,14 +216,14 @@ Inference requests from the agent never leave the sandbox directly. OpenShell intercepts them and routes to the configured provider: ```text -Agent (sandbox) ──▶ OpenShell gateway ──▶ NVIDIA Endpoint (build.nvidia.com) +Compatible agent (sandbox) ──▶ OpenShell gateway ──▶ Provider endpoint ``` When you select the Model Router provider, the OpenShell gateway routes to a host-side router process instead of a single upstream model. The router selects from the configured pool, then calls the upstream NVIDIA endpoint with the credential held outside the sandbox. Some model and provider combinations need agent-specific compatibility setup. -NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so OpenClaw and Hermes fixes can be tested and reviewed independently. +NemoClaw keeps those declarations under `nemoclaw-blueprint/model-specific-setup//` so fixes for each supported agent can be tested and reviewed independently. Refer to [Inference Options](../inference/inference-options) for provider configuration details. diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx new file mode 100644 index 0000000000..8fab0200e9 --- /dev/null +++ b/docs/reference/commands-nemohermes.mdx @@ -0,0 +1,1498 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "NemoHermes CLI Commands Reference" +sidebar-title: "Commands" +description: "Full CLI reference for standalone NemoHermes commands and Hermes-specific in-sandbox commands." +description-agent: "Includes the full CLI reference for standalone NemoHermes commands and Hermes-specific in-sandbox commands. Use when looking up a specific `nemohermes` subcommand, flag, argument, or exit code." +keywords: ["nemohermes cli commands", "hermes command reference", "nemohermes command reference"] +content: + type: "reference" +--- +{/* This file is generated from docs/reference/commands.mdx by scripts/sync-agent-variant-docs.ts. Do not edit by hand. */} + +The `nemohermes` alias is the primary interface for managing Hermes sandboxes through NemoClaw. +It is installed automatically by the installer (`curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_AGENT=hermes bash`). +Most commands in this reference share the same shape as `nemohermes`; use `nemohermes` when you want Hermes selected by default. +For guidance on when to use `nemohermes`, `nemohermes`, or the underlying `openshell` CLI, see [CLI Selection Guide](cli-selection-guide). + +## Agent Selection + +Use `nemohermes` for the Hermes variant. +It is equivalent to running `nemohermes` with `--agent hermes` during onboarding or `NEMOCLAW_AGENT=hermes` for other commands. +Hermes-specific sections below describe the OpenAI-compatible API endpoint, optional Hermes dashboard, Hermes config under `/sandbox/.hermes`, and provider updates that patch `config.yaml`. + +```console +$ nemohermes onboard # equivalent to: nemohermes onboard --agent hermes +$ nemohermes my-sandbox connect # same command shape as: nemohermes my-sandbox connect +``` + +## In-Sandbox Commands + +Hermes does not use the OpenClaw `/nemohermes` chat slash command. +Use the host-side `nemohermes` commands for lifecycle, status, policy, and inference operations. +The in-sandbox Hermes integration installs the NemoClaw Hermes plugin, which exposes NemoClaw tools such as `nemohermes_status`, `nemohermes_info`, and `nemohermes_reload_skills`, plus an `on_session_start` hook. + +## Standalone Host Commands + +The CLI handles host-side operations that run outside the selected agent runtime. + +### `nemohermes help`, `nemohermes --help`, `nemohermes -h` + +Show the top-level usage summary and command groups. +Running `nemohermes` with no arguments shows the same help output. + +```console +$ nemohermes help +``` + +### `nemohermes --version`, `nemohermes -v` + +Print the installed NemoClaw CLI version. + +```console +$ nemohermes --version +``` + +### `nemohermes resources` + +Display host hardware inventory and configured sandbox resource profiles. +Use `--json` for machine-readable CPU, memory, GPU, Kubernetes allocatable-capacity, and profile data. + +```console +$ nemohermes resources [--json] +``` + +If the gateway is not running, Kubernetes allocatable fields are omitted and host CPU/RAM totals are still shown. + +### `nemohermes onboard` + +Run the interactive setup wizard (recommended for new installs). +The wizard creates an OpenShell gateway, registers inference providers, builds the sandbox image, and creates the sandbox. +Use this command for new installs and for recreating a sandbox after changes to policy or configuration. + +```console +$ nemohermes onboard [--non-interactive] [--resume | --fresh] [--recreate-sandbox] [--gpu | --no-gpu] [--from ] [--name ] [--sandbox-gpu | --no-sandbox-gpu] [--sandbox-gpu-device ] [--agent ] [--control-ui-port ] [--yes | -y] [--no-ollama-autostart] [--yes-i-accept-third-party-software] +``` + +For Hermes, use the alias or pass the agent explicitly: + +```console +$ nemohermes onboard [options] +$ nemohermes onboard --agent hermes [options] +``` + +#### `--resume` and `--fresh` + +NemoClaw records onboarding progress so interrupted runs can continue. +Use `--resume` to continue a resumable onboarding session with the provider, model, sandbox name, agent, and custom Dockerfile path recorded by the original run. +If the recorded session conflicts with flags you pass on the recovery run, NemoClaw exits and tells you to either rerun with the original settings or start over. + +Use `--fresh` to discard the saved onboarding session and start the wizard from the beginning. +This clears stale or failed session state before NemoClaw creates a new session record. +The installer also accepts `--fresh` and forwards it to `nemohermes onboard`, which skips automatic resume detection. +`--resume` and `--fresh` are mutually exclusive. + + +For NemoClaw-managed environments, use `nemohermes onboard` when you need to create or recreate the OpenShell gateway or sandbox. +Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemohermes onboard`. + + +Use `--fresh` to ignore any saved onboarding session and restart the wizard from scratch. This is useful after an interrupted `nemohermes onboard` run when you want to discard saved state instead of continuing it with `--resume`. + +The installer detects existing sandbox sessions before onboarding and prints a warning if any are found. +To make the installer abort instead of continuing, set `NEMOCLAW_SINGLE_SESSION=1`: + +```console +$ NEMOCLAW_SINGLE_SESSION=1 curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +When existing sandboxes were created with OpenShell earlier than `0.0.37`, the installer prompts before running the new automatic gateway upgrade path. +For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the installer to back up registered sandbox state, retire the old gateway, install the current supported OpenShell release, and restore state during onboarding. +The automatic path is disabled if the existing `nemohermes` CLI does not advertise `backup-all`; preserve sandbox state manually before retiring the old gateway in that case. +To perform those steps manually, run `nemohermes backup-all`, retire the old gateway registration with `openshell gateway remove nemohermes || openshell gateway destroy -g nemohermes || openshell gateway destroy` (both verbs are tried so the right one runs on either OpenShell release), stop any remaining privileged host gateway with `sudo pkill -f openshell-gateway`, then rerun the installer as `curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1 bash`. + +The wizard prompts for a provider first, then collects the provider credential if needed. +Supported non-experimental choices include NVIDIA Endpoints, OpenAI, Anthropic, Google Gemini, and compatible OpenAI or Anthropic endpoints. +Credentials are registered with the OpenShell gateway and never persisted to host disk. See [Credential Storage](../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. +It then prompts for optional web search and messaging channels, builds and starts the sandbox, and asks for a **policy tier** that controls the default set of network policy presets applied to the sandbox. +Three tiers are available: + +| Tier | Description | +|------|-------------| +| Restricted | Base sandbox only. No third-party network access beyond inference and core agent tooling. | +| Balanced (default) | Full dev tooling and web search when the active agent supports web search. Package installs, model downloads, and inference. No messaging platform access. | +| Open | Broad access across third-party services including messaging and productivity. Agent-specific unsupported presets are filtered out. | + +After selecting a tier, the wizard shows a combined preset and access-mode screen where you can include or exclude individual presets and toggle each between read and read-write access. +For details on tiers and the presets each includes, see [Network Policies](network-policies#policy-tiers). + +In non-interactive mode, set the tier with `NEMOCLAW_POLICY_TIER` (default: `balanced`): + +```console +$ NEMOCLAW_POLICY_TIER=restricted nemohermes onboard --non-interactive --yes-i-accept-third-party-software +``` + +`NEMOCLAW_POLICY_MODE` controls how non-interactive onboarding reconciles the tier-derived suggestions against the sandbox's currently-applied presets. +The default is `suggested`, which is *additive*. +Onboarding applies tier defaults and preserves any presets you previously added with [`nemohermes policy-add`](#nemohermes-name-policy-add) across re-onboards. +Use `custom` with `NEMOCLAW_POLICY_PRESETS` when you want the explicit list to be authoritative. +Onboarding removes any preset that is not in the list. +`skip` leaves the applied set untouched and does not apply tier defaults. +NemoClaw filters tier suggestions and resume selections by active agent support, so unsupported presets such as Brave Search are not reapplied to agents that do not support them. + +| Value | Behaviour | +|-------|-----------| +| `suggested` (default) | Apply tier defaults and preserve any extra presets already applied. Aliases: `default`, `auto`. | +| `custom` | Apply exactly `NEMOCLAW_POLICY_PRESETS`. Previously-applied presets not in the list are removed. Alias: `list`. | +| `skip` | Skip the policy step entirely. Aliases: `none`, `no`. | + +For non-interactive onboarding, you must explicitly accept the third-party software notice: + +```console +$ nemohermes onboard --non-interactive --yes-i-accept-third-party-software +``` + +or: + +```console +$ NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 nemohermes onboard --non-interactive +``` + +For scripted installer runs, pass explicit acceptance to the `bash` side of the installer pipe: + +```console +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash +``` + +If the installer cannot prompt for the notice in a terminal and no explicit acceptance is set, it exits before installing Node.js or the NemoClaw CLI. + +To enable Brave Search in non-interactive mode, set: + +```console +$ BRAVE_API_KEY=... \ + nemohermes onboard --non-interactive +``` + +`BRAVE_API_KEY` enables Brave Search in non-interactive mode and also enables `web_fetch`. +If Brave Search key validation fails in non-interactive mode, onboarding prints a warning, skips web search setup, and continues with the rest of the sandbox setup. +After fixing the key, re-enable web search with `nemohermes config web-search`. + +The wizard prompts for a sandbox name. +Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. +The CLI rejects names that do not match these rules. +It also prints a `Try: ` recovery line whenever it can derive a valid lowercase, hyphen-separated form from the input, so passing `--name MyAssistant` reports `Try: myassistant`. +Names that match global CLI commands (`status`, `list`, `debug`, etc.) are rejected to avoid routing conflicts. +Use `--agent ` to target a specific installed agent profile during onboarding. + +Use `--control-ui-port ` to choose the host dashboard port for a sandbox. +The value must be an integer from `1024` through `65535`. +This flag takes precedence over `CHAT_UI_URL`, `NEMOCLAW_DASHBOARD_PORT`, the previous registry value, and the default port. + +If you enable Slack during onboarding, the wizard collects both the Bot Token (`SLACK_BOT_TOKEN`) and the App-Level Token (`SLACK_APP_TOKEN`). +Socket Mode requires both tokens. +The app-level token is stored in a dedicated `slack-app` OpenShell provider and forwarded to the sandbox alongside the bot token. +The wizard also accepts optional `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` values so you can restrict Slack DMs, channel `@mention` users, and channel IDs before the sandbox image is built. + +If you enable Discord during onboarding, the wizard can also prompt for a Discord Server ID, whether the bot should reply only to `@mentions` or to all messages in that server, and an optional Discord User ID. +NemoClaw bakes those values into the sandbox image as Discord guild workspace config so the bot can respond in the selected server, not just in DMs. +If you leave the Discord User ID blank, the guild config omits the user allowlist and any member of the configured server can message the bot. +Guild responses remain mention-gated by default unless you opt into all-message replies. + +If you enable Telegram during onboarding, the wizard can also prompt for whether group chats should reply only to `@mentions` or to all group messages. +Set `TELEGRAM_REQUIRE_MENTION=1` for non-interactive onboarding when you want mention-only group replies. +Pairing and `TELEGRAM_ALLOWED_IDS` still govern direct messages. + +If you run onboarding again with the same sandbox name and choose a different inference provider or model, NemoClaw detects the drift and recreates the sandbox so the running agent config matches your selection. +In interactive mode, the wizard asks for confirmation before delete and recreate. +In non-interactive mode, NemoClaw recreates automatically when the stored selection is readable and differs; if NemoClaw cannot read the stored selection, NemoClaw reuses by default. +Set `NEMOCLAW_RECREATE_SANDBOX=1` to force recreation even when no drift is detected. + +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. +Set `NEMOCLAW_RECREATE_WITHOUT_BACKUP=1` to skip the pre-recreate backup. +The destination sandbox starts with a fresh workspace. + +For Hermes, the backed-up paths come from `agents/hermes/manifest.yaml`, including `/sandbox/.hermes` state such as memories, sessions, skills, plugins, cron, logs, plans, workspace, messaging platform state, and `runtime/state.db`. + +Before creating the gateway, the wizard runs preflight checks. +It verifies that Docker is reachable, warns on untested runtimes such as Podman, and prints host remediation guidance when prerequisites are missing. +The preflight also enforces the OpenShell version range declared in the blueprint (`min_openshell_version` and `max_openshell_version`). +If the installed OpenShell version falls outside this range, onboarding exits with an actionable error and a link to compatible releases. +For fresh OpenShell installs, NemoClaw queries published OpenShell releases and asks the installer to use a release that fits the blueprint range. +If release metadata is unavailable, the installer uses its bundled fallback pin and the post-install version gate still enforces the range. + +When NemoClaw finds an existing gateway to reuse, it probes the host gateway HTTP endpoint before declaring the gateway reusable. +If the container is running but the upstream is still warming up (for example, immediately after a Docker daemon restart), NemoClaw rebuilds the gateway instead of trusting stale metadata. +On the Docker-driver gateway path, preflight stays read-only when it detects a stale gateway (for example, a Docker-driver runtime env hash drift). +It prints a `⚠ Gateway will be recreated when sandbox creation starts` notice and defers the actual teardown to step `[2/8] Starting OpenShell gateway`. +This means pressing `Ctrl+C` between preflight and step `[2/8]` leaves the running gateway and existing sandbox containers untouched, so `nemohermes onboard` is safe to run just to check preflight output. +For Linux Docker-driver gateways, onboarding also checks that a helper container on the OpenShell Docker network can reach `host.openshell.internal:`. +If a host firewall blocks that sandbox path, onboarding exits with a `sudo ufw allow from to any port proto tcp` command before it reports the gateway healthy. +Tune the wait via `NEMOCLAW_REUSE_HEALTH_POLL_COUNT` (default `6`) and `NEMOCLAW_REUSE_HEALTH_POLL_INTERVAL` (default `5` seconds). +The poll count is clamped to a minimum of `1` so the probe always runs at least once, and the interval is clamped to a minimum of `0` (no sleep between attempts). + +#### `--from ` + +Build the sandbox image from a custom Dockerfile instead of the stock NemoClaw image. +The entire parent directory of the specified file is used as the Docker build context, so any files your Dockerfile references (scripts, config, etc.) must live alongside it. +Onboarding skips common large directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. +It also skips credential-style files and directories such as `.env*`, `.ssh/`, `.aws/`, `.netrc`, `.npmrc`, `secrets/`, `*.pem`, and `*.key`. +Other build outputs such as `dist/`, `target/`, or `build/` are still included. +If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts. +If the directory contains unreadable files (for example, Windows system files visible in WSL), onboarding exits with an error suggesting you move the Dockerfile to a dedicated directory. + +```console +$ nemohermes onboard --from path/to/Dockerfile +``` + +The Dockerfile path must exist. +Missing paths fail during command parsing before preflight, gateway setup, inference setup, or sandbox creation starts. + +The file can have any name; if it is not already named `Dockerfile`, onboard copies it to `Dockerfile` inside the staged build context automatically. +To create an isolated build context, create a dedicated directory that contains only the Dockerfile and the files it needs: + +```text +build-dir/ +├── Dockerfile +└── files-used-by-COPY/ +``` + +All NemoClaw build arguments (`NEMOCLAW_MODEL`, `NEMOCLAW_PROVIDER_KEY`, `NEMOCLAW_INFERENCE_BASE_URL`, etc.) are injected as `ARG` overrides at build time, so declare them in your Dockerfile if you need to reference them. + +In non-interactive mode, the path can also be supplied via the `NEMOCLAW_FROM_DOCKERFILE` environment variable. +You must also supply a sandbox name via `--name ` or `NEMOCLAW_SANDBOX_NAME` so a `--from` build cannot silently clobber the default `my-assistant` sandbox. + +```console +$ NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_FROM_DOCKERFILE=path/to/Dockerfile NEMOCLAW_SANDBOX_NAME=my-build nemohermes onboard +``` + +If a `--resume` is attempted with a different `--from` path than the original session, onboarding exits with a conflict error rather than silently building from the wrong image. + +#### `--name ` + +Set the sandbox name without going through the interactive prompt. +The same name format and reserved-name rules that the wizard enforces apply here too. Names must be 1 to 63 characters, lowercase, start with a letter, contain only letters, numbers, and internal hyphens, and end with a letter or number. +Names that match a NemoClaw CLI command (`status`, `list`, `debug`, etc.) are rejected up front. + +```console +$ nemohermes onboard --non-interactive --name my-build --from path/to/Dockerfile +``` + +The flag wins over `NEMOCLAW_SANDBOX_NAME`. +When prompting is possible, `NEMOCLAW_SANDBOX_NAME` fills the interactive default so you can press Enter to accept it. +When prompting is impossible (no TTY or `--non-interactive`), the env var is also honoured so existing CI scripts keep working. +Combining `--from ` with non-interactive onboarding requires one of `--name` or `NEMOCLAW_SANDBOX_NAME`; otherwise onboarding exits rather than silently defaulting to `my-assistant` and clobbering the default sandbox. + +### `nemohermes onboard --from` + +Use a custom Dockerfile for the sandbox image. +This variant of `nemohermes onboard` accepts a `--from ` argument to build the sandbox from a user-supplied Dockerfile instead of the default NemoClaw image. + +```console +$ nemohermes onboard --from ./Dockerfile.custom +``` + +### GPU passthrough + +When `nemohermes onboard` detects an NVIDIA GPU on the host, it enables OpenShell GPU passthrough at both the gateway and sandbox level by default. +Detection proceeds along two paths. The `nvidia-smi`-based paths (the primary `--query-gpu=name,memory.total,memory.free` probe and the unified-memory `--query-gpu=name` fallback) require `nvidia-smi` to succeed and, on hosts whose firmware does not classify as a known NVIDIA platform (DGX Spark, DGX Station, Jetson, or Tegra), additionally require that the GPU name does not match the placeholder family observed on the Windows-on-ARM WSL2 nvidia-smi shim (`JMJWOA-Generic-*`) and that either the host is not ARM64 Linux (the observed shim is Windows-on-ARM only) or the NVIDIA kernel driver is bound (`/proc/driver/nvidia/` present), so that placeholder shims on non-NVIDIA hardware are not mistaken for real GPUs. +Jetson/Tegra hosts that ship without `nvidia-smi` continue to be detected via the devicetree firmware fallback (`/sys/firmware/devicetree/base/model`) or the Tegra device-node fallback (`/dev/nvhost-gpu`, `/dev/nvhost-ctrl-gpu`, `/dev/nvhost-ctrl`, or `/dev/nvmap`); both bypass the trust-tier gate above. +Use `--no-gpu` to opt out when you want host-side inference providers only and do not need direct GPU access inside the sandbox. +Use `--gpu` to require GPU passthrough and fail fast if an NVIDIA GPU is not detected. +Use `--sandbox-gpu` or `--no-sandbox-gpu` to control only direct NVIDIA GPU access inside the sandbox. +Use `--sandbox-gpu --sandbox-gpu-device ` to pass a specific OpenShell GPU device selector to `openshell sandbox create`; device selectors require explicit sandbox GPU enablement. +On Linux Docker-driver gateways, NemoClaw can create the sandbox first and then recreate the OpenShell-managed Docker container with NVIDIA GPU access when that compatibility path is needed. +If the patch fails, onboarding keeps diagnostics and prints a manual cleanup command rather than deleting the failed sandbox automatically. + +Prerequisites: + +- Ensure NVIDIA GPU drivers are installed and working. + - On generic NVIDIA hosts, `nvidia-smi` must succeed. + - On Jetson/Tegra hosts shipping without `nvidia-smi`, the devicetree firmware fallback substitutes. +- NVIDIA Container Toolkit configured for Docker. + +When GPU passthrough is enabled and a gateway already exists without it, onboarding first checks whether replacing the CPU-only gateway is safe. +If no other registered sandbox depends on that gateway, or if `--recreate-sandbox` is recreating the only registered sandbox with the same name, onboarding cleans up the stale gateway and continues. +If other sandboxes depend on the gateway or Docker state is unclear, onboarding exits without cleanup and prints targeted destroy or gateway-removal guidance. +To add GPU to an existing sandbox, rerun with `--recreate-sandbox`. +Set `NEMOCLAW_DOCKER_GPU_PATCH=0` only when you need to bypass the Linux Docker-driver compatibility patch during troubleshooting. + +### `nemohermes list` + +List all registered sandboxes with their model, provider, and policy presets. +Pass `--json` for machine-readable output that includes a `schemaVersion`, the default sandbox, recovery metadata, and the sandbox inventory. +Sandboxes with an active SSH session are marked with a `●` indicator so you can tell at a glance which sandbox you are already connected to in another terminal. +When a sandbox has a recorded dashboard port, the output includes its local dashboard URL. + +```console +$ nemohermes list [--json] +$ nemohermes list --json +``` + +### `nemohermes deploy` + + +The `nemohermes deploy` command is deprecated. +Prefer provisioning the remote host separately, then running the standard NemoClaw installer and `nemohermes onboard` on that host. + + +Deploy NemoClaw to a remote GPU instance through [Brev](https://brev.nvidia.com). +This command remains as a compatibility wrapper for the older Brev-specific bootstrap flow. +The Brev instance name is the positional argument. +The sandbox name comes from `NEMOCLAW_SANDBOX_NAME` and defaults to `my-assistant`; invalid sandbox names fail before Brev provisioning starts. + +```console +$ nemohermes deploy +``` + +### `nemohermes connect` + +Connect to a sandbox by name. +If the sandbox is not yet in the `Ready` phase, `connect` polls `openshell sandbox list` every few seconds and prints the current phase. This gives you progress output right after onboarding, when the 2.4 GB image is still pulling, instead of a silent hang. +Control the wait budget with `NEMOCLAW_CONNECT_TIMEOUT` (integer seconds, default `120`). When the deadline expires, `connect` exits non-zero with the last-seen phase. + +On a TTY, a one-shot hint prints before dropping into the sandbox shell. +The hint is agent-aware. It names the correct TUI command for the sandbox's agent and reminds you to use `/exit` to leave the chat before `exit` returns you to the host shell. +Set `NEMOCLAW_NO_CONNECT_HINT=1` to suppress the hint in scripted workflows. +If the sandbox is running an outdated agent version, a non-blocking warning prints before connecting with a `nemohermes rebuild` hint. +If another terminal is already connected to the sandbox, `connect` prints a note with the number of existing sessions before proceeding. Multiple concurrent sessions are allowed. + +`connect` does not pull or serve a model itself, but it does inspect `NEMOCLAW_VLLM_MODEL` if you exported it for the managed-vLLM install path. +An unknown slug or a gated model (for example `deepseek-r1-distill-70b`) with no `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` exits non-zero with the same error the installer would emit, before any sandbox readiness probe or SSH attach. +Unset the variable, or supply the missing token, before retrying. + +After a host reboot, the OpenShell gateway rotates its SSH host keys. +`connect` detects the resulting identity drift, prunes stale `openshell-*` entries from `~/.ssh/known_hosts`, and retries automatically. +You no longer need to re-run `nemohermes onboard` after a reboot in this case. + +```console +$ nemohermes my-assistant connect [--probe-only] +``` + +The `--probe-only` flag verifies the sandbox is reachable over SSH and exits without opening a shell. +Use it for health checks and scripted readiness probes. + +### `nemohermes exec` + +Run a single command non-interactively in a running sandbox via the OpenShell exec endpoint. +The command runs as the sandbox user with `HOME=/sandbox`, so in-sandbox tooling resolves NemoClaw-provisioned config the same way it does for `connect` and `openshell sandbox connect`. +This is the supported substitute for `docker exec` on the sandbox container; raw `docker exec` runs as root and lands on `HOME=/root`, where the selected agent config is not present. + +Hermes config resolves under `/sandbox/.hermes`. + +```console +$ nemohermes my-assistant exec -- hermes --version +$ nemohermes my-assistant exec --workdir /sandbox/workspace -- ls -la +``` + +Everything after `--` is forwarded verbatim to the sandbox command, including flags the inner command needs. +The exit code is the remote command's exit code. + +| Flag | Description | +|------|-------------| +| `--workdir ` | Working directory inside the sandbox | +| `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | +| `--timeout ` | Timeout in seconds (`0` means no timeout) | + +### `nemohermes recover` + +Restart the in-sandbox gateway and re-establish the host-side dashboard port-forward without opening an SSH session. +Use this after a sandbox pod restart, a sandbox crash, or whenever `nemohermes status` reports the gateway is not running but the sandbox is alive. + +`recover` runs the same recovery the `connect` command performs as a side effect, but without dropping into a shell, so it is safe to call from scripts and automation. +It is idempotent. +If the gateway is already running, the command exits zero with a probe message and makes no changes. + +```console +$ nemohermes my-assistant recover +``` + +### `nemohermes status` + +Show sandbox status, health, and inference configuration. + +Pass `--json` to emit a structured per-sandbox report instead of the text renderer. +The JSON output includes at least `schemaVersion`, `name`, `found`, `model`, `provider`, `phase`, `gatewayState`, `inferenceHealth`, `rpcIssue`, `hostGpuDetected`, `sandboxGpuEnabled`, `sandboxGpuMode`, `sandboxGpuDevice`, `openshellDriver`, `openshellVersion`, and `policies`. +`openshellDriver` and `openshellVersion` are always strings (falling back to `"unknown"` when the registry has no value), so consumers can rely on `typeof` checks. +The command exits non-zero when the sandbox is missing locally, the gateway state is not `present`, or the gateway reports a schema/protobuf mismatch (mirrored as `rpcIssue`). +The alias form `nemohermes status --json` requires the sandbox to be registered locally; the canonical form `nemohermes sandbox status --json` is the one to use from automation that may run against an unknown sandbox name, since it still emits a JSON document with `found: false` instead of a text error. + +```console +$ nemohermes my-assistant status +$ nemohermes my-assistant status --json +$ nemohermes sandbox status my-assistant --json +``` + +The command probes every inference provider and reports one of three states on the `Inference` line: + +| State | Meaning | +|-------|---------| +| `healthy` | The provider endpoint returned a reachable response. | +| `unreachable` | The probe failed. The output includes the endpoint URL and a remediation hint. | +| `not probed` | The endpoint URL is not known (for example, `compatible-*` providers). | +| `not verified` | NemoClaw could not verify the sandbox or gateway state, so it skips inference probing. | + +Local providers (Ollama, vLLM) probe the host-side health endpoint. +Remote providers (NVIDIA Endpoints, OpenAI, Anthropic, Gemini) use a lightweight reachability check; any HTTP response, including `401` or `403`, counts as reachable. +No API keys are sent. + +For Local Ollama, the command also probes the authenticated proxy and prints an `Inference (auth proxy)` line when a proxy token is available. +Use that line to distinguish a healthy backend from a broken proxy path that the sandbox uses for inference. + +For cloud-only providers, the output omits the NIM status line unless a NIM container is registered or an unexpected NIM container is running. + +If the sandbox or gateway cannot be verified, the command exits non-zero instead of reporting healthy inference from stale registry state. +Gateway and dashboard health checks treat HTTP `401` from device auth as a live service, not as an offline gateway. + +A `Connected` line reports whether the sandbox has any active SSH sessions and, if so, how many. +The sandbox list in the status output includes the dashboard port suffix for sandboxes with a recorded dashboard port. + +The Policy section displays the live enforced policy (fetched via `openshell policy get --full`), which reflects presets added or removed after sandbox creation. +When OpenShell reports an active policy version, the displayed YAML `version` line uses that active version instead of the static schema version. +If the sandbox is running an outdated agent version, the output includes an `Update` line with the available version and a `nemohermes rebuild` hint. + +When other sandboxes have the same messaging channel enabled (Telegram, Discord, or Slack) with the same bot token, the output includes a cross-sandbox overlap warning so you can resolve the conflict before messages start dropping. +The command also tails `/tmp/gateway.log` inside the default sandbox and flags Telegram `409 Conflict` errors that indicate a duplicate consumer for the bot token. + +```console +$ nemohermes my-assistant status +``` + +#### Checking the Hermes version + +NemoClaw pins the Hermes version inside the sandbox image at build time, not at runtime. +The Hermes agent manifest declares the expected version and the `hermes --version` probe command. +Existing sandboxes do not auto-upgrade when a newer NemoClaw release ships a newer Hermes pin; you upgrade by rebuilding the sandbox. + +`nemohermes status` prints the running Hermes version on the `Agent` line: + +```console +$ nemohermes my-assistant status +... + Agent: Hermes v2026.5.16 +... +``` + +If the sandbox is running an older Hermes version than this NemoClaw release expects, `status` and `connect` add an `Update` line pointing at `nemohermes rebuild` to pick up the newer version. +The rebuild reuses the existing sandbox name and persisted credentials, so messaging tokens and provider keys carry over. + +### `nemohermes doctor` + +Run a focused health check for one sandbox and the host services it depends on. +The command checks the local CLI build, Docker daemon, OpenShell CLI, NemoClaw gateway container, gateway port mapping, live sandbox state, inference route, provider reachability, messaging channel conflicts, Ollama reachability, and the cloudflared tunnel state. + +Warnings do not make the command fail. +Failed checks exit non-zero so scripts can use `doctor` as a readiness gate. +Use `--json` for machine-readable output. + +```console +$ nemohermes my-assistant doctor [--json] +``` + +### `nemohermes exec` + +Run a command non-interactively inside a running sandbox through the OpenShell exec endpoint. +The command runs as the sandbox user with `HOME=/sandbox` and exits with the remote command's exit code. +Use `--` to separate `exec` options from the command you want to run inside the sandbox. + +```console +$ nemohermes my-assistant exec [--workdir ] [--tty|--no-tty] [--timeout ] -- [args...] +``` + +| Flag | Description | +|------|-------------| +| `--workdir ` | Set the working directory inside the sandbox | +| `--tty`, `--no-tty` | Allocate or disable a pseudo-terminal; defaults to auto-detection | +| `--timeout ` | Timeout in seconds. Use `0` for no timeout | + +### `nemohermes logs` + +View sandbox logs. +Use `--follow` to stream output in real time. +Use `--tail ` or `-n ` to limit the number of returned lines. +Use `--since ` to show recent logs only, such as `5m`, `1h`, or `30s`. +The command reads both agent gateway output and OpenShell audit events, so policy denials appear alongside the gateway log stream. +If one log source is unavailable, NemoClaw prints a warning and keeps reading the remaining source. +NemoClaw's `--tail ` flag is a line-count flag; the lower-level `openshell logs --tail` flag means follow live output, so use `openshell logs -n ` when running OpenShell directly for a fixed line count. + +```console +$ nemohermes my-assistant logs [--follow] [--tail |-n ] [--since ] +``` + +### `nemohermes dashboard-url` + +`dashboard-url` is not applicable to Hermes sandboxes because Hermes exposes an OpenAI-compatible API endpoint instead of the OpenClaw dashboard URL. +Use `nemohermes my-assistant status` to find the forwarded API endpoint. +The Hermes API remains on port `8642` and uses `/v1` for OpenAI-compatible clients. +If you enabled `NEMOCLAW_HERMES_DASHBOARD=1`, use the optional Hermes dashboard port from the status output instead. + +### `nemohermes gateway-token` + +`gateway-token` is not applicable to Hermes sandboxes. +Hermes API access uses bearer-token authentication configured through the Hermes runtime, not the OpenClaw gateway token. +If you need the endpoint for an OpenAI-compatible client, use `nemohermes my-assistant status` and the API URL it reports. + +### `nemohermes destroy` + +Stop the NIM container, remove the host-side Docker image built during onboard, and delete the sandbox. +This removes the sandbox from the registry. +For Ollama-backed sandboxes, `destroy` also asks Ollama to unload currently loaded models and clears stale auth proxy state on a best-effort basis. + + +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). +If you want to upgrade the sandbox while preserving state, use `nemohermes rebuild` instead. + + +If another terminal has an active SSH session to the sandbox, `destroy` prints an active-session warning and requires a second confirmation before it proceeds. +Pass `--yes`, `-y`, or `--force` to skip the prompt in scripted workflows. +By default, `destroy` preserves the shared NemoClaw gateway. +Pass `--cleanup-gateway` to remove the shared gateway when destroying the last sandbox, or `--no-cleanup-gateway` to force preservation when environment defaults request cleanup. + +```console +$ nemohermes my-assistant destroy [--yes|-y|--force] [--cleanup-gateway|--no-cleanup-gateway] +``` + +### `nemohermes policy-add` + +Add a policy preset to a sandbox. +Presets extend the baseline network policy with additional endpoints. +Before applying, the command shows which endpoints the preset would open and prompts for confirmation. + +```console +$ nemohermes my-assistant policy-add +``` + +To apply a specific preset without the interactive picker, pass its name as a positional argument: + +```console +$ nemohermes my-assistant policy-add pypi --yes +``` + +The positional form is required in scripted workflows. +Set `NEMOCLAW_NON_INTERACTIVE=1` instead of `--yes` if you want the same behavior from an environment variable. +If the preset name is unknown or already applied, the command exits non-zero with a clear error. +Custom preset files are tracked with the sandbox that applied them. +`policy-list`, `policy-add`, and `policy-remove` compare the local registry and live gateway state using that sandbox-scoped preset metadata, so custom presets do not appear missing just because they are not part of the built-in preset catalog. + +| Flag | Description | +|------|-------------| +| `--from-file ` | Apply a custom preset YAML file instead of a built-in preset | +| `--from-dir ` | Apply every custom preset YAML file in a directory in lexicographic order | +| `--yes`, `--force` | Skip the confirmation prompt (requires a preset name, `--from-file`, or `--from-dir`) | +| `--dry-run` | Preview the endpoints a preset would open without applying changes | + +Use `--dry-run` to audit a preset before applying it: + +```console +$ nemohermes my-assistant policy-add --dry-run +``` + +Apply a custom preset file when you need to grant access to an endpoint that is not covered by a built-in preset: + +```console +$ nemohermes my-assistant policy-add --from-file ./presets/my-internal-api.yaml +``` + +For batch workflows, apply all preset files from a directory: + +```console +$ nemohermes my-assistant policy-add --from-dir ./presets/ --yes +``` + +Review every host in custom preset files before applying them. +Custom presets bypass the built-in preset review process and can widen sandbox egress. + +### `nemohermes policy-list` + +List available policy presets and show which ones are applied to the sandbox. +The command cross-references the local registry against the live gateway state (via `openshell policy get`), so it flags presets that are applied in one place but not the other. +This catches desync caused by external edits to the gateway policy or stale registry entries after a manual rollback. + +```console +$ nemohermes my-assistant policy-list +``` + +### `nemohermes policy-remove` + +Remove a previously applied policy preset from a sandbox. +The command lists only the presets currently applied, prompts you to select one, shows the endpoints that would be removed, and asks for confirmation before narrowing egress. + +```console +$ nemohermes my-assistant policy-remove +``` + +To remove a specific preset non-interactively, pass its name as a positional argument: + +```console +$ nemohermes my-assistant policy-remove pypi --yes +``` + +Set `NEMOCLAW_NON_INTERACTIVE=1` as an alternative to `--yes`. +If the preset is unknown or not currently applied, the command exits non-zero with a clear error. + +| Flag | Description | +|------|-------------| +| `--yes`, `--force` | Skip the confirmation prompt (requires a preset name) | +| `--dry-run` | Preview which endpoints would be removed without applying changes | + +Unchecking a preset in the onboard TUI checkbox also removes it from the sandbox. + +### `nemohermes hosts-add` + +Add a host alias to the sandbox pod template. +Use this when a sandbox needs a stable LAN-only name, such as a local SearXNG or internal model endpoint, without dropping to `docker exec` and `kubectl patch`. + +```console +$ nemohermes my-assistant hosts-add searxng.local 192.168.1.105 +``` + +The command validates the hostname and IP address, rejects duplicate hostnames, and patches `spec.podTemplate.spec.hostAliases` on the sandbox resource. + +| Flag | Description | +|------|-------------| +| `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it | + +### `nemohermes hosts-list` + +List host aliases configured on the sandbox resource. + +```console +$ nemohermes my-assistant hosts-list +``` + +### `nemohermes hosts-remove` + +Remove a hostname from the sandbox `hostAliases` list. + +```console +$ nemohermes my-assistant hosts-remove searxng.local +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Print the JSON patch for the resulting `hostAliases` list without applying it | + +### `nemohermes channels list` + +List the messaging channels NemoClaw knows about (`telegram`, `discord`, `slack`, `wechat`, `whatsapp`) with a short description. +The command is a static reference; it does not consult credentials or the running sandbox. +WeChat and WhatsApp are experimental. + +```console +$ nemohermes my-assistant channels list +``` + +### `nemohermes channels add ` + +Register a messaging channel with the sandbox and rebuild so the image picks up the new channel. +Channels fall into three login modes: + +- **Token paste** (`telegram`, `discord`, `slack`): the command prompts for any missing token and registers it with the OpenShell gateway. +- **Host-side QR** (`wechat`, experimental): the command renders an iLink QR code on the host and you scan it from WeChat on your phone. + On confirm, NemoClaw captures the bot token, registers it with the OpenShell gateway, and stores non-secret per-account metadata (`WECHAT_ACCOUNT_ID`, `WECHAT_BASE_URL`, `WECHAT_USER_ID`) for the in-sandbox bridge. + NemoClaw automatically adds the scanning operator's WeChat user ID to `WECHAT_ALLOWED_IDS`. + Supply additional comma-separated IDs to authorize more DM senders. + NemoClaw advertises WeChat for both OpenClaw (the `@tencent-weixin/openclaw-weixin` plugin) and Hermes (the built-in iLink WeChat adapter). +- **In-sandbox QR** (`whatsapp`, experimental): the command records the channel without a host-side token or OpenShell credential provider. + NemoClaw advertises WhatsApp for OpenClaw and Hermes sandboxes; after rebuild, run `openclaw channels login --channel whatsapp` for OpenClaw or `hermes whatsapp` for Hermes. + 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. +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. +With the preset file in place, NemoClaw applies it to the sandbox before the rebuild so the bridge has egress to its upstream API. +When the apply step itself fails after the registry write on a fresh add, NemoClaw attempts to roll back the bridge providers, the `messagingChannels` entry, and any staged environment credentials, then exits without prompting for a rebuild; if any gateway-side step (provider detach or delete) fails the rollback continues and prints a `Rollback could not fully clean ` warning so the operator can clean up manually. +When the same failure happens on a re-add of an already-enabled channel, NemoClaw restores the prior `messagingChannels` entry, restores staged environment credentials when available, restores registry credential hashes, and attempts to re-upsert the prior bridge providers, but flags `gateway-providers` as residual because the in-flight upsert may have left the gateway with the new token; verify the gateway bridge before relying on the channel. +Restore the preset YAML and re-run `nemohermes channels add `. +For Telegram, Discord, and Slack, a rebuild triggered by `channels add` also verifies that the selected bridge starts and reports credential, startup, or plugin discovery warnings. + +```console +$ nemohermes my-assistant channels add telegram +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Validate the channel name and matching policy preset without prompting for credentials, contacting the gateway, or rebuilding | + +Slack requires both `SLACK_BOT_TOKEN` (bot user OAuth) and `SLACK_APP_TOKEN` (app-level Socket Mode token); the command prompts for each in turn. +Optional Slack allowlists come from `SLACK_ALLOWED_USERS` and `SLACK_ALLOWED_CHANNELS` at rebuild time. +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 ` + +Clear the stored credentials for a messaging channel and rebuild the sandbox so the image drops the channel. +Running `remove` for a channel that was never configured is a no-op against the credentials file and still triggers the rebuild prompt. +When the bridge provider is attached to a live sandbox, NemoClaw detaches it before deleting the provider from the OpenShell gateway. +If the matching built-in policy preset is applied, such as `telegram`, `discord`, `slack`, `wechat`, or `whatsapp`, NemoClaw also removes that preset so the upstream API is no longer allow-listed after the channel is gone. +NemoClaw also strips the channel from `session.policyPresets` so a subsequent `onboard --resume` does not re-apply the preset on the next rebuild. + +For QR-paired channels (today: WhatsApp), NemoClaw destructively clears the in-sandbox session directory before the rebuild so the `state_dirs` backup does not restore the auth blob and let the channel reconnect: + +- OpenClaw: `/sandbox/.openclaw//` (for example `/sandbox/.openclaw/whatsapp/`). +- Hermes: `/sandbox/.hermes/platforms//` (for example `/sandbox/.hermes/platforms/whatsapp/`). + +The cleanup tries `openshell sandbox exec` first and falls back to SSH if the exec wrapper does not return the success sentinel. If both transports fail (the sandbox is stopped, the gateway is down, or SSH cannot reach it) the command refuses to proceed to the rebuild and asks you to start the sandbox and re-run, so a half-removed state cannot leave stale Baileys auth files behind for the next rebuild to restore. + +```console +$ nemohermes my-assistant channels remove telegram +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Report the channel that would be removed without clearing credentials or rebuilding | + +As with `channels add`, `NEMOCLAW_NON_INTERACTIVE=1` skips the rebuild prompt and queues the change for a manual `nemohermes rebuild`. +If you omit the required `` argument, the CLI prints the `channels remove ` usage with the supported channel list. + +Host-side removal is the supported path because agent channel config is baked into the container image at build time (`/sandbox/.openclaw/openclaw.json` for OpenClaw and `/sandbox/.hermes/.env` for Hermes); agent-specific channel removals inside the sandbox would modify the running config but not persist changes across rebuilds. + +### `nemohermes channels stop ` + +Pause a single messaging bridge (`telegram`, `discord`, `slack`, `wechat`, or `whatsapp`) without clearing its credentials. +The channel is marked disabled in the per-sandbox registry, and the sandbox is rebuilt so the onboard step skips registering the bridge with the gateway. +The provider stays registered with the OpenShell gateway, so a later `channels start` brings the bridge back without re-entering tokens. + +```console +$ nemohermes my-assistant channels stop telegram +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Report the channel that would be disabled without updating the registry or rebuilding | + +Use `channels stop` instead of `channels remove` when you want to pause a bridge temporarily. `channels remove` is destructive to credentials; `channels stop` is not. + +### `nemohermes channels start ` + +Re-enable a channel previously paused with `channels stop`. The channel is removed from the disabled list, the sandbox is rebuilt, and the bridge registers with the gateway again using the stored credentials. + +```console +$ nemohermes my-assistant channels start telegram +``` + +| Flag | Description | +|------|-------------| +| `--dry-run` | Report the channel that would be re-enabled without updating the registry or rebuilding | + +### `nemohermes channels status` + +Run channel-specific runtime diagnostics. For WhatsApp the command probes the sandbox to separately report pairing/session state, the Noise WebSocket connection, inbound event delivery, and policy/config coverage; a paired channel with no observed inbound delivery exits non-zero with verdict `idle` so an unhealthy bridge cannot pass as healthy. + +```bash +nemohermes my-assistant channels status --channel whatsapp +``` + +| Flag | Description | +|------|-------------| +| `--channel ` | Channel to inspect; defaults to `whatsapp` when registered | +| `--json` | Emit the diagnostic report as JSON (exit non-zero when the verdict is not `healthy` or `unknown`) | + +The probe is bounded by an in-sandbox `openshell sandbox exec` with a hard timeout, captures only short matched bridge log signals (e.g. `connection.open`, `401 unauthorized`, `qr expired`), and never forwards message bodies to the host diagnostic output. + +### `nemohermes skill install ` + +Deploy a skill directory to a running sandbox. +The command validates the `SKILL.md` frontmatter (a `name` field is required), uploads all non-dot files preserving subdirectory structure, and performs agent-specific post-install steps. + +```console +$ nemohermes my-assistant skill install ./my-skill/ +``` + +The skill directory must contain a `SKILL.md` file with YAML frontmatter that includes a `name` field. +Skill names must contain only alphanumeric characters, dots, hyphens, and underscores. + +Hermes plugins are different from NemoClaw skills. +`skill install` uploads agent skills, while Hermes plugin configuration is managed by the Hermes runtime and the NemoClaw Hermes plugin baked into the sandbox image. + +Run `nemohermes skill install --help` to print usage for this subcommand. +If you pass a plugin-shaped directory to `skill install`, the CLI prints a plugin-specific hint instead of treating it as a missing skill file. + +Files with names starting with `.` (dotfiles) are skipped and listed in the output. +Files with unsafe path characters are rejected to prevent shell injection. + +If the skill already exists on the sandbox, the command updates it in place and preserves chat history. +For new installs, the agent session index is refreshed so the agent discovers the skill on the next session. + +### `nemohermes skill remove ` + +Remove an installed skill from a running sandbox by skill name. +The command validates the skill name, removes the sandbox upload directory, and refreshes the agent session index so the remaining skills are rediscovered on the next session. + +For Hermes, restart the Hermes gateway if prompted so the removal takes effect. + +```bash +nemohermes my-assistant skill remove my-skill +``` + +Use the skill name from the `SKILL.md` frontmatter, not the local directory name. +Skill names must contain only alphanumeric characters, dots, hyphens, and underscores, and cannot be `.` or `..`. + +### `nemohermes rebuild` + +Upgrade a sandbox to the current agent version while preserving workspace state. +The command backs up workspace state, destroys the old sandbox (including its host-side Docker image), recreates it with the current image via `onboard --resume`, and restores workspace state into the new sandbox. +Credentials are stripped from backups before storage. +Policy presets applied to the old sandbox are reapplied to the new one so your egress rules survive the rebuild. +The recorded sandbox GPU mode is preserved across rebuild. +A sandbox onboarded with an explicit GPU opt-out (stored as `sandboxGpuMode: "0"`, plus legacy registry entries that only record `gpuEnabled: false`) is recreated with the same opt-out, so the inner `onboard --resume` skips the Docker CDI GPU preflight on hosts without an NVIDIA GPU. +Auto-mode sandboxes remain auto. + +```console +$ nemohermes my-assistant rebuild [--yes|-y|--force] [--verbose|-v] +``` + +| Flag | Description | +|------|-------------| +| `--yes`, `-y`, `--force` | Skip the confirmation prompt | +| `--verbose`, `-v` | Log SSH commands, exit codes, and session state (also enabled by `NEMOCLAW_REBUILD_VERBOSE=1`) | + +If another terminal has an active SSH session to the sandbox, `rebuild` prints an active-session warning and requires confirmation before destroying the sandbox. +Pass `--yes`, `-y`, or `--force` to skip the prompt in scripted workflows. + +The sandbox must be running for the backup step to succeed. +If an archive command reports partial output while still producing usable data, `rebuild` keeps the captured backup entries and reports only the manifest-defined paths that could not be archived. +If any required state path still cannot be backed up, `rebuild` exits before destroying the original sandbox. + +After restore, the command restores Hermes manifest-defined state and starts the rebuilt Hermes gateway with the regenerated `/sandbox/.hermes` config. + +### `nemohermes update` + +Check for a NemoClaw CLI update and, when requested, run the maintained installer flow. +This command is a discoverable CLI wrapper around the supported installer path: + +```console +$ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash +``` + +```console +$ nemohermes update [--check] [--yes|-y] +``` + +| Flag | Description | +|------|-------------| +| `--check` | Show the current version, latest maintained version, install type, and maintained update command without changing anything | +| `--yes`, `-y` | Skip the confirmation prompt and run the maintained installer flow | + +`nemohermes update` updates the host-side NemoClaw installation. +The maintained installer flow follows the admin-promoted `lkg` release tag by default, so it may trail the newest semver or `latest` tag while validation completes. +It does not replace `nemohermes upgrade-sandboxes`; use that command to inspect or rebuild existing sandboxes after the CLI has been updated. +When the command is running from a source checkout, it reports that state and does not replace the checkout with a global package install. + +### `nemohermes upgrade-sandboxes` + +Rebuild sandboxes whose base image is older than the one currently pinned by NemoClaw. +NemoClaw resolves the digest of `ghcr.io/nvidia/nemohermes/sandbox-base:latest` from the registry, then compares it against the digest each sandbox was created with. +Sandboxes that match the current digest are left alone. + +```console +$ nemohermes upgrade-sandboxes [--check] [--auto] [--yes|-y] +``` + +| Flag | Description | +|------|-------------| +| `--check` | List stale sandboxes without rebuilding any of them. Exits non-zero if any are stale. | +| `--auto` | Rebuild every stale sandbox without prompting. Used by the installer to upgrade in place. | +| `--yes`, `-y` | Skip the confirmation prompt for the rebuild plan. | + +Each rebuild reuses the same workspace backup-and-restore flow as `nemohermes rebuild`, so workspace files survive the upgrade. +If the registry is unreachable (offline or firewalled hosts), NemoClaw falls back to the unpinned `:latest` tag and reports that the digest could not be resolved instead of failing. + +### `nemohermes backup-all` + +Back up all registered running sandboxes to `~/.nemohermes/rebuild-backups/`. +Sandboxes that are not running are skipped. + +```console +$ nemohermes backup-all +``` + +The installer calls `backup-all` automatically before onboarding to protect against data loss during OpenShell upgrades. + +### `nemohermes snapshot create` + +Create a timestamped snapshot of sandbox state. +Snapshots are stored in `~/.nemohermes/rebuild-backups//`. + +```console +$ nemohermes my-assistant snapshot create +``` + +| Flag | Description | +|------|-------------| +| `--name