diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 583f66a2a3..9ed77865f1 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -78,9 +78,9 @@ repos: hooks: - id: platform-matrix-sync name: Sync platform matrix to docs - entry: bash -c 'python3 scripts/generate-platform-docs.py && git add README.md docs/inference/inference-options.mdx' + entry: bash -c 'python3 scripts/generate-platform-docs.py && git add docs/get-started/prerequisites.mdx docs/inference/inference-options.mdx' language: system - files: ^(ci/platform-matrix\.json|README\.md|docs/inference/inference-options\.mdx|scripts/generate-platform-docs\.py)$ + files: ^(ci/platform-matrix\.json|docs/get-started/prerequisites\.mdx|docs/inference/inference-options\.mdx|scripts/generate-platform-docs\.py)$ pass_filenames: false priority: 3 diff --git a/README.md b/README.md index 223bdbd4bc..c75c698b41 100644 --- a/README.md +++ b/README.md @@ -3,224 +3,38 @@ SPDX-License-Identifier: Apache-2.0 --> -# 🦞 NVIDIA NemoClaw: Reference Stack for Running OpenClaw in OpenShell +# NVIDIA NemoClaw: Reference Stack for Sandboxed AI Agents in OpenShell - [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/NVIDIA/NemoClaw/blob/main/LICENSE) [![Security Policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md) -[![Project Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/NVIDIA/NemoClaw/blob/main/docs/about/release-notes.mdx) +[![Project Status](https://img.shields.io/badge/status-alpha-orange)](https://docs.nvidia.com/nemoclaw/latest/about/release-notes.html) [![Discord](https://img.shields.io/badge/Discord-Join-7289da)](https://discord.gg/XFpfPv9Uvx) - - -NVIDIA NemoClaw is an open source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants more safely. -It installs the [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) runtime, part of NVIDIA Agent Toolkit, which provides additional security for running autonomous agents. - +NVIDIA NemoClaw is an open source reference stack for running always-on AI agents more safely inside [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes. +It provides guided onboarding, a hardened blueprint, routed inference, network policy, and lifecycle management through a single CLI. -> **Alpha software** -> -> NemoClaw is available in early preview starting March 16, 2026. +> [!NOTE] +> NemoClaw is **alpha software**. > This software is not production-ready. -> Interfaces, APIs, and behavior may change without notice as we iterate on the design. -> The project is shared to gather feedback and enable early experimentation. -> We welcome issues and discussion from the community while the project evolves. +> Interfaces, APIs, and behavior may change without notice. +> See [Release Notes](https://docs.nvidia.com/nemoclaw/latest/about/release-notes.html) for the current version. -NemoClaw adds guided onboarding, a hardened blueprint, state management, OpenShell-managed channel messaging, routed inference, and layered protection on top of the [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) runtime. For the full feature list, refer to [Overview](https://docs.nvidia.com/nemoclaw/latest/about/overview.html). For the system diagram, component model, and blueprint lifecycle, refer to [How It Works](https://docs.nvidia.com/nemoclaw/latest/about/how-it-works.html) and [Architecture](https://docs.nvidia.com/nemoclaw/latest/reference/architecture.html). +**Supported agents:** -## Getting Started +- [OpenClaw](https://openclaw.ai) (default) +- [Hermes](https://get-hermes.ai/) -Follow these steps to install NemoClaw and run your first sandboxed OpenClaw agent. +For capabilities, architecture, security controls, and the full feature list, see the [NemoClaw documentation](https://docs.nvidia.com/nemoclaw/latest/). - +## Get Started -### Prerequisites +Review [Prerequisites](https://docs.nvidia.com/nemoclaw/latest/get-started/prerequisites.html) before installing. +For Hermes, set `NEMOCLAW_AGENT=hermes` before running the installer, or use the `nemohermes` alias after install. -Before getting started, check the prerequisites to ensure you have the necessary software and hardware to run NemoClaw. - -#### Hardware - -| Resource | Minimum | Recommended | -|----------|----------------|------------------| -| CPU | 4 vCPU | 4+ vCPU | -| RAM | 8 GB | 16 GB | -| Disk | 20 GB free | 40 GB free | - -The sandbox image is approximately 2.4 GB compressed. During image push, the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline, which buffers decompressed layers in memory. On machines with less than 8 GB of RAM, this combined usage can trigger the OOM killer. If you cannot add memory, configuring at least 8 GB of swap can work around the issue at the cost of slower performance. - -#### Software - -| Dependency | Version | -|------------|----------------------------------| -| Node.js | 22.16 or later | -| npm | 10 or later | -| Platform | See below | - -#### OpenShell Lifecycle - -For NemoClaw-managed environments, use `nemoclaw onboard` when you need to create or recreate the OpenShell gateway or sandbox. -Avoid `openshell self-update`, `npm update -g openshell`, `openshell gateway start --recreate`, or `openshell sandbox create` directly unless you intend to manage OpenShell separately and then rerun `nemoclaw onboard`. - -#### Container Runtimes - -The following table lists tested platform and runtime combinations. -Availability is not limited to these entries, but untested configurations may have issues. - - -| OS | Container runtime | Status | Notes | -|----|-------------------|--------|-------| -| Linux | Docker | Tested | Primary tested path. | -| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Install Xcode Command Line Tools (`xcode-select --install`) and start the runtime before running the installer. | -| DGX Spark | Docker | Tested | Use the standard installer and `nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). | -| Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | Requires WSL2 with Docker Desktop backend. | - - -For platform-specific pre-setup (for example, Windows WSL 2), see [Prerequisites](https://docs.nvidia.com/nemoclaw/latest/get-started/prerequisites.html). - -### Install NemoClaw and Onboard OpenClaw Agent - -Download and run the installer script. -The script installs Node.js if it is not already present, then runs the guided onboard wizard to create a sandbox, configure inference, and apply security policies. - -> **ℹ️ Note** -> -> NemoClaw creates a fresh OpenClaw instance inside the sandbox during the onboarding process. -> -> The installer runs as your normal user and does not require `sudo` or root. -> It installs Node.js via nvm and NemoClaw via npm, both into user-local directories. -> Docker must be installed and running before you run the installer. Installing Docker may require elevated privileges on Linux. - -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -``` - -The piped installer prompts through your terminal. In headless scripts or CI, -pass explicit acceptance to the `bash` side of the pipe: - -```bash -curl -fsSL https://www.nvidia.com/nemoclaw.sh | NEMOCLAW_NON_INTERACTIVE=1 NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 bash -``` - -If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH. -If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal. - -When the install completes, a summary confirms the running environment: - -```text -────────────────────────────────────────────────── -Sandbox my-assistant (Landlock + seccomp + netns) -Model nvidia/nemotron-3-super-120b-a12b (NVIDIA Endpoints) -────────────────────────────────────────────────── -Run: nemoclaw my-assistant connect -Status: nemoclaw my-assistant status -Logs: nemoclaw my-assistant logs --follow -────────────────────────────────────────────────── - -To change settings later: - Model: nemoclaw inference get - nemoclaw inference set --model --provider --sandbox my-assistant - -[INFO] === Installation complete === -``` - -### Chat with the Agent - -Connect to the sandbox, then chat with the agent through the TUI or the CLI. - -```bash -nemoclaw my-assistant connect -``` - -In the sandbox shell, open the OpenClaw terminal UI and start a chat: - -```bash -openclaw tui -``` - -Alternatively, send a single message and print the response: - -```bash -openclaw agent --agent main -m "hello" --session-id test -``` - -### Model Router (Experimental) - -NemoClaw includes an optional model router that automatically picks the most efficient model for each query. Instead of sending every request to a single large model, the router uses a lightweight encoder to predict which model in a pool can handle each query correctly, then routes to the cheapest one that meets an accuracy threshold. - -The router uses the [NVIDIA LLM Router v3](https://github.com/NVIDIA-AI-Blueprints/llm-router/tree/v3) prefill routing engine and runs on the host as a LiteLLM proxy. The sandbox reaches it through the OpenShell gateway and continues to call `https://inference.local/v1`; do not probe `localhost:4000` or `host.openshell.internal` directly from inside the sandbox. - -#### Enable during onboard - -Select **Model Router (experimental)** during the onboard wizard, or set `NEMOCLAW_PROVIDER=routed` for non-interactive mode: - -```bash -NEMOCLAW_PROVIDER=routed nemoclaw onboard --non-interactive -``` - -The onboard wizard starts the router, configures the OpenShell provider, and creates the sandbox. The router process runs on the host on port 4000. - -#### Configure the model pool - -Edit `nemoclaw-blueprint/router/pool-config.yaml` to define which models the router can choose from: - -```yaml -routing: - method: prefill - checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt - tolerance: 0.20 - encoder: Qwen/Qwen3.5-0.8B - -models: - - name: nano - litellm_model: "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B" - cost_per_m_input_tokens: 0.05 - api_base: "https://inference-api.nvidia.com" - - - name: super - litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3" - cost_per_m_input_tokens: 0.10 - api_base: "https://inference-api.nvidia.com" -``` - -The `tolerance` parameter controls the accuracy-cost tradeoff: 0.0 always picks the most accurate model, 1.0 always picks the cheapest, and 0.20 (default) allows up to 20 percentage points below the best for a cheaper model. - -#### Architecture - -The router runs on the host, not inside the sandbox: - -```text -Sandbox (OpenClaw) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API - └── PrefillRouter selects model -``` - -Credentials flow through the OpenShell provider system. The sandbox never sees raw API keys. - -### Uninstall - -To remove NemoClaw and all resources created during setup, run the CLI's built-in uninstall command: - -```bash -nemoclaw uninstall -``` - -| Flag | Effect | -|--------------------|-----------------------------------------------------| -| `--yes` | Skip the confirmation prompt. | -| `--keep-openshell` | Leave OpenShell binaries installed. | -| `--delete-models` | Also remove NemoClaw-pulled Ollama models. | - -`nemoclaw uninstall` runs the version-pinned `uninstall.sh` shipped with your installed CLI, with no network fetch at uninstall time. - -If the `nemoclaw` CLI is missing or broken, fall back to the hosted script: - -```bash -curl -fsSL https://raw.githubusercontent.com/NVIDIA/NemoClaw/refs/heads/main/uninstall.sh | bash -``` - -For a full comparison of the two forms, see [`nemoclaw uninstall` vs. the hosted `uninstall.sh`](https://docs.nvidia.com/nemoclaw/latest/reference/commands.html#nemoclaw-uninstall-vs-the-hosted-uninstallsh). - -For troubleshooting installation or onboarding issues, see the [Troubleshooting guide](https://docs.nvidia.com/nemoclaw/latest/reference/troubleshooting.html). - - +| Agent | Guide | +|-------|-------| +| OpenClaw (default) | [Quickstart with OpenClaw](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart.html) | +| Hermes | [Quickstart with Hermes](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart-hermes.html) | ## Documentation @@ -241,49 +55,8 @@ Refer to the following pages on the official documentation website for more info | [CLI Commands](https://docs.nvidia.com/nemoclaw/latest/reference/commands.html) | Full NemoClaw CLI command reference. | | [Troubleshooting](https://docs.nvidia.com/nemoclaw/latest/reference/troubleshooting.html) | Common issues and resolution steps. | -### Build Docs Locally - -The public documentation site is built with Fern. -The repo pins the Fern CLI version in `fern/fern.config.json`. -Use the npm scripts so every docs command uses that pinned version. - -```bash -npm run docs -npm run docs:live -``` - -To publish a branch-based Fern preview whenever docs files change, run: - -```bash -npm run docs:preview:watch -``` - -## Project Structure - -The following directories make up the NemoClaw repository. - -```text -NemoClaw/ -β”œβ”€β”€ bin/ # CLI entry point and library modules (CJS) -β”œβ”€β”€ nemoclaw/ # TypeScript plugin (Commander CLI extension) -β”‚ └── src/ -β”‚ β”œβ”€β”€ blueprint/ # Runner, snapshot, SSRF validation, state -β”‚ β”œβ”€β”€ commands/ # Slash commands, migration state -β”‚ └── onboard/ # Onboarding config -β”œβ”€β”€ nemoclaw-blueprint/ # Blueprint YAML and network policies -β”‚ └── router/ -β”‚ β”œβ”€β”€ pool-config.yaml # Model pool and routing config -β”‚ └── llm-router/ # LLM Router v3 submodule (prefill routing engine) -β”œβ”€β”€ scripts/ # Install helpers, setup, automation -β”œβ”€β”€ test/ # Integration and E2E tests -β”œβ”€β”€ fern/ # Fern site configuration and shared assets -└── docs/ # User-facing docs (Fern MDX plus legacy MyST source during migration) -``` - ## Community -Join the NemoClaw community to ask questions, share feedback, and report issues. - - [Discord](https://discord.gg/XFpfPv9Uvx) - [GitHub Discussions](https://github.com/NVIDIA/NemoClaw/discussions) - [GitHub Issues](https://github.com/NVIDIA/NemoClaw/issues) diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 8cd564c580..b992f15eff 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -3,15 +3,15 @@ # SPDX-License-Identifier: Apache-2.0 title: "NemoClaw Architecture Overview" sidebar-title: "Architecture Overview" -description: "Learn how NemoClaw combines a host CLI, sandbox plugin, and versioned blueprint to move OpenClaw into a controlled sandbox." +description: "Learn how NemoClaw combines a host CLI, sandbox plugin, and versioned blueprint to run supported agents in a controlled sandbox." description-agent: "Describes how NemoClaw works internally: CLI, plugin, blueprint runner, OpenShell orchestration, inference routing, and protection layers. Use for sandbox lifecycle and architecture mechanics; not for product definition (Overview) or multi-project placement (Ecosystem)." keywords: ["how nemoclaw works", "nemoclaw sandbox lifecycle blueprint"] content: type: "concept" --- -This page explains how NemoClaw runs OpenClaw inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. +This page explains how NemoClaw runs supported agents inside an OpenShell sandbox and how the gateway connects the agent to inference, integrations, and policy. -NemoClaw does not replace OpenClaw or OpenShell. +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. You can use that setup directly or adapt it for your own OpenShell integration. @@ -30,7 +30,7 @@ The diagram has the following components: | Users and operators | Start from the CLI, installer, dashboard, or an end-user channel. | | NemoClaw control | Collects configuration, runs onboarding, prepares the blueprint, and asks OpenShell to create or update resources. | | OpenShell gateway | Owns sandbox lifecycle, networking, policy enforcement, inference routing, and integration egress. | -| NemoClaw sandbox | Runs OpenClaw with the NemoClaw plugin, the selected blueprint contents, and supporting tools. | +| NemoClaw sandbox | Runs the onboarded agent with the selected blueprint contents and supporting tools. OpenClaw sandboxes also load the NemoClaw plugin. | | 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. | @@ -71,7 +71,7 @@ This separation keeps the sandbox plugin small while allowing host orchestration ## Sandbox Creation -When you run `nemoclaw onboard`, NemoClaw creates an OpenShell sandbox that runs OpenClaw in an isolated container. +When you run `nemoclaw 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. @@ -106,6 +106,6 @@ 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](/get-started/quickstart) to launch your first sandbox. +- Follow the [Quickstart with OpenClaw](/get-started/quickstart) or [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. diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 1b7c9a8e0f..a4d0dd9edb 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -3,23 +3,24 @@ # SPDX-License-Identifier: Apache-2.0 title: "Overview of NVIDIA NemoClaw" sidebar-title: "Overview" -description: "NemoClaw is an open-source reference stack that simplifies running OpenClaw always-on assistants more safely." -description-agent: "Explains what NemoClaw covers: onboarding, lifecycle management, and OpenClaw operations within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works." -keywords: ["nemoclaw overview", "openclaw always-on assistants", "nvidia openshell", "nvidia nemotron"] +description: "NemoClaw is an open-source reference stack for running sandboxed AI agents more safely inside OpenShell." +description-agent: "Explains what NemoClaw covers: onboarding, lifecycle management, and agent operations within OpenShell containers, plus capabilities and why it exists. Use when users ask what NemoClaw is or what the project provides. For ecosystem placement or OpenShell-only paths, use the Ecosystem page; for internal mechanics, use How It Works." +keywords: ["nemoclaw overview", "openclaw always-on assistants", "hermes agent", "nvidia openshell", "nvidia nemotron"] content: type: "concept" --- -NVIDIA NemoClaw is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants more safely. -NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. -It incorporates policy-based privacy and security guardrails, giving you control over your agents’ behavior and data handling. -This enables self-evolving claws to run more safely in clouds, on prem, RTX PCs and DGX Spark. +NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside OpenShell containers. +NemoClaw provides onboarding, lifecycle management, and agent operations for supported runtimes in OpenShell sandboxes. +It incorporates policy-based privacy and security guardrails, giving you control over your agents' behavior and data handling. +This enables self-evolving agents to run more safely in clouds, on prem, RTX PCs, and DGX Spark. NemoClaw pairs hosted models on inference providers or local endpoints with a hardened sandbox, routed inference, and declarative egress policy so deployment stays safer and more repeatable. -The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell); NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run OpenClaw there. +The sandbox runtime comes from [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell). +NemoClaw adds the blueprint, `nemoclaw` CLI, onboarding, and related tooling as the reference way to run supported agents there. | Capability | Description | |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| Sandbox OpenClaw | Creates an OpenShell sandbox pre-configured for OpenClaw, with filesystem and network policies applied from the first boot. | +| Sandbox supported agents | Creates an OpenShell sandbox pre-configured for your selected agent, with filesystem and network policies applied from the first boot. | | Route inference | Configures OpenShell inference routing so agent traffic goes to the provider and model you chose during onboarding (NVIDIA Endpoints, OpenAI, Anthropic, Gemini, compatible endpoints, local Ollama, and others). The agent uses `inference.local` inside the sandbox; credentials stay on the host. | | Manage the lifecycle | Handles blueprint versioning, digest verification, and sandbox setup. | @@ -57,7 +58,7 @@ You can use NemoClaw for various use cases including the following. | Use Case | Description | |---------------------------|----------------------------------------------------------------------------------------------| -| Always-on assistant | Run an OpenClaw assistant with controlled network access and operator-approved egress. | +| Always-on assistant | Run a sandboxed agent with controlled network access and operator-approved egress. | | Sandboxed testing | Test agent behavior in a locked-down environment before granting broader permissions. | | Remote GPU deployment | Deploy a sandboxed agent to a remote GPU instance for persistent operation. | @@ -67,6 +68,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install - [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](/get-started/quickstart) to install NemoClaw and run your first sandboxed agent. +- [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. diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx index ede016d2c4..fc577f2e0f 100644 --- a/docs/get-started/prerequisites.mdx +++ b/docs/get-started/prerequisites.mdx @@ -63,12 +63,14 @@ The following table lists tested platform and runtime combinations. Availability is not limited to these entries, but untested configurations can have issues. The table is generated from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoClaw/blob/main/ci/platform-matrix.json), the single source of truth kept in sync by CI and QA. +{/* platform-matrix:begin */} | OS | Container runtime | Status | Notes | |----|-------------------|--------|-------| | Linux | Docker | Tested | Primary tested path. | | macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Install Xcode Command Line Tools (`xcode-select --install`) and start the runtime before running the installer. | | DGX Spark | Docker | Tested | Use the standard installer and `nemoclaw onboard`. For an end-to-end walkthrough with local Ollama inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). | | Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | Requires WSL2 with Docker Desktop backend. | +{/* platform-matrix:end */} ## Next Steps diff --git a/docs/get-started/quickstart-hermes.mdx b/docs/get-started/quickstart-hermes.mdx index 14a7b5abe2..2d54fb5731 100644 --- a/docs/get-started/quickstart-hermes.mdx +++ b/docs/get-started/quickstart-hermes.mdx @@ -14,11 +14,6 @@ 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. - -The Hermes agent option is experimental. -Interfaces, defaults, and supported features may change without notice, and it is not recommended for production use. - - Review the [Prerequisites](/get-started/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. diff --git a/docs/index.mdx b/docs/index.mdx index 081207586f..1e77a0356b 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -3,8 +3,8 @@ # SPDX-License-Identifier: Apache-2.0 title: "NVIDIA NemoClaw" sidebar-title: "NVIDIA NemoClaw Developer Guide" -description: "NemoClaw is an open-source reference stack that simplifies running OpenClaw always-on assistants more safely, with a single command and packaged agent skills." -keywords: "NemoClaw, OpenClaw, OpenShell, AI agents, agent skills, sandboxing, inference routing" +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" position: 1 --- @@ -36,14 +36,14 @@ import { CommandTerminal } from "./_components/CommandTerminal"; ]} /> -NVIDIA NemoClaw is an open-source reference stack that simplifies running [OpenClaw](https://openclaw.ai) always-on assistants more safely. -NemoClaw provides onboarding, lifecycle management, and OpenClaw operations within OpenShell containers. -It installs the [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) runtime, part of NVIDIA Agent Toolkit, setting up an environment designed for executing agents with additional security and inference routing capabilities. +NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes. +NemoClaw provides onboarding, lifecycle management, and agent operations within OpenShell containers. +It installs the OpenShell runtime, part of NVIDIA Agent Toolkit, and sets up an environment designed for executing agents with additional security and inference routing capabilities. NemoClaw also ships user skills for AI coding assistants, so tools such as Cursor and Claude Code can guide you through setup, inference, policy management, monitoring, deployment, security, and troubleshooting from the same documentation. ## Get Started -Install NemoClaw and run your first sandboxed agent. +Install NemoClaw and run the onboard wizard. @@ -59,7 +59,10 @@ curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash -For more detailed guidance on getting started, refer to [Quickstart](/get-started/quickstart). +| Agent | Guide | +|-------|-------| +| OpenClaw (default) | [Quickstart with OpenClaw](/get-started/quickstart) | +| Hermes | [Quickstart with Hermes](/get-started/quickstart-hermes) | ## Use NemoClaw User Skills diff --git a/docs/inference/inference-options.mdx b/docs/inference/inference-options.mdx index f96fe705d5..3b7ef7a68c 100644 --- a/docs/inference/inference-options.mdx +++ b/docs/inference/inference-options.mdx @@ -83,7 +83,46 @@ When you select it, NemoClaw starts the router proxy on the host, waits for its The sandbox does not call the router port directly. The router model pool lives in `nemoclaw-blueprint/router/pool-config.yaml`. +Edit that file to define which models the router can choose from. The default pool routes between NVIDIA-hosted Nemotron models and uses the `tolerance` value to choose the lowest-cost model whose predicted quality stays within the configured threshold. + +```yaml +routing: + method: prefill + checkpoint: llm-router/checkpoints/prefill_router_qwen08b.pt + tolerance: 0.20 + encoder: Qwen/Qwen3.5-0.8B + +models: + - name: nano + litellm_model: "openai/nvidia/nvidia/Nemotron-3-Nano-30B-A3B" + cost_per_m_input_tokens: 0.05 + api_base: "https://inference-api.nvidia.com" + + - name: super + litellm_model: "openai/nvidia/nvidia/nemotron-3-super-v3" + cost_per_m_input_tokens: 0.10 + api_base: "https://inference-api.nvidia.com" +``` + +The `tolerance` parameter controls the accuracy-cost tradeoff. + +| Value | Behavior | +|-------|----------| +| `0.0` | Always pick the most accurate model. | +| `0.20` | Allow up to 20 percentage points below the best for a cheaper model (default). | +| `1.0` | Always pick the cheapest model. | + +The router runs on the host, not inside the sandbox. + +```text +Sandbox (agent) ──> OpenShell Gateway (L7 proxy) ──> Model Router (:4000) ──> NVIDIA API + └── PrefillRouter selects model +``` + +Credentials flow through the OpenShell provider system. +The sandbox never sees raw API keys. + To use the router in scripted setup, set: ```console diff --git a/scripts/generate-platform-docs.py b/scripts/generate-platform-docs.py index 070a434f7e..391f8b9ac1 100755 --- a/scripts/generate-platform-docs.py +++ b/scripts/generate-platform-docs.py @@ -7,9 +7,9 @@ between sentinel comments in target files. Sentinel pairs: - / - / - {/* provider-status:begin */} / {/* provider-status:end */} + / (Markdown only) + {/* platform-matrix:begin */} / {/* platform-matrix:end */} (MDX) + {/* provider-status:begin */} / {/* provider-status:end */} (MDX) Usage: python3 scripts/generate-platform-docs.py # patch files in place @@ -33,10 +33,7 @@ "platform-matrix", "platforms", [ - # README.md is the patch target. docs/get-started/platform-setup/ - # index.md pulls the same table in via Sphinx `{include}` so the - # generator does not need a second target there. - REPO_ROOT / "README.md", + REPO_ROOT / "docs" / "get-started" / "prerequisites.mdx", ], ), (