## File: README.md # NVIDIA NemoClaw: Reference Stack for Sandboxed AI Agents in OpenShell [](https://github.com/NVIDIA/NemoClaw/blob/main/LICENSE) [](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md) [](https://discord.gg/XFpfPv9Uvx) NVIDIA NemoClaw is an open source reference stack for running supported AI agents more safely inside [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes. It provides guided onboarding, managed inference, network policy, managed integrations, snapshots, and lifecycle operations through the NemoClaw CLI and its agent-specific aliases. **Supported agents:** - [OpenClaw](https://openclaw.ai) (default) - [Hermes](https://get-hermes.ai/) - [LangChain Deep Agents Code](https://docs.langchain.com/oss/python/deepagents/code/overview) For capabilities, architecture, security controls, and the full feature list, see the [NemoClaw documentation](https://docs.nvidia.com/nemoclaw/latest/). ## Get Started ### Start with Your Coding Agent Use the starter prompt when you want Cursor, Claude Code, Codex, Copilot, or another local coding agent to install NemoClaw with you. **[Copy the NemoClaw starter prompt](https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/home.html#from-your-coding-agent)**. The prompt tells your agent to use NemoClaw docs and skills, ask one question at a time, run commands only with your approval, and keep secrets out of chat. ### Install Using the Installer in Your Terminal Review [Prerequisites](https://docs.nvidia.com/nemoclaw/latest/get-started/prerequisites.html) before installing. On a supported DGX or Windows Subsystem for Linux (WSL) host, press Enter at the `Run express install with these settings? [Y/n]:` prompt to use the recommended preset settings for that platform. Express install mode installs OpenClaw by default. If you accept, refer to [NemoClaw Quickstart with OpenClaw](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart.html). Enter `n` if you want to choose Hermes or LangChain Deep Agents Code, a sandbox name, an inference provider, and a model interactively. When connecting to a Hermes sandbox from a light terminal, NemoClaw may install a managed `nemoclaw-light` Hermes skin for readable assistant text; it removes that managed skin state again when the terminal no longer needs it and preserves any user-selected Hermes skin. | 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) | | LangChain Deep Agents Code | [Quickstart with LangChain Deep Agents Code](https://docs.nvidia.com/nemoclaw/latest/user-guide/deepagents/get-started/quickstart.html) | ## Documentation Refer to the following pages on the official documentation website for more information on NemoClaw. | Page | Description | |------|-------------| | [Overview](https://docs.nvidia.com/nemoclaw/latest/about/overview.html) | What NemoClaw does and how it fits together. | | [Architecture Overview](https://docs.nvidia.com/nemoclaw/latest/about/how-it-works.html) | High-level overview of the host CLI, agent integration layer, blueprint, sandbox lifecycle, and protection layers. | | [Ecosystem](https://docs.nvidia.com/nemoclaw/latest/about/ecosystem.html) | How OpenClaw, OpenShell, and NemoClaw form a stack and when to use NemoClaw versus OpenShell alone. | | [Architecture Details](https://docs.nvidia.com/nemoclaw/latest/reference/architecture.html) | Detailed description of agent integration structure, blueprint lifecycle, sandbox environment, and host-side state. | | [Prerequisites](https://docs.nvidia.com/nemoclaw/latest/get-started/prerequisites.html) | Hardware, software, and supported platforms, with any platform-specific pre-setup. | | [Choose an Inference Provider](https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/inference/learn-and-choose/choose-inference-provider) | Supported providers, validation, and routed inference configuration. | | [Network Policies](https://docs.nvidia.com/nemoclaw/latest/reference/network-policies.html) | Baseline rules, operator approval flow, and egress control. | | [Customize Network Policy](https://docs.nvidia.com/nemoclaw/latest/network-policy/customize-network-policy.html) | Static and dynamic policy changes, presets. | | [Security Best Practices](https://docs.nvidia.com/nemoclaw/latest/security/best-practices.html) | Controls reference, risk framework, and posture profiles for sandbox security. | | [Sandbox Hardening](https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/manage-sandboxes/configure-sandboxes/review-sandbox-hardening) | Container security measures, capability drops, process limits. | | [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. | ## Community Join the NemoClaw community to ask questions, share feedback, and report issues. NemoClaw is an alpha project, so maintainers review issues, discussions, and pull requests on a best effort basis without guaranteed response timelines. | Need | Channel | |------|---------| | Setup or usage questions | [GitHub Discussions](https://github.com/NVIDIA/NemoClaw/discussions) or [Discord](https://discord.gg/XFpfPv9Uvx) | | Reproducible bugs | [GitHub Issues](https://github.com/NVIDIA/NemoClaw/issues) | | Feature proposals | Start with [GitHub Discussions](https://github.com/NVIDIA/NemoClaw/discussions), then open an issue when the scope is clear | | Current priorities | [Current Priorities](#current-priorities) | | Contribution help | [CONTRIBUTING.md](CONTRIBUTING.md) | | Security vulnerabilities | Use the private channels in [SECURITY.md](SECURITY.md); do not open public issues | ## Contributing We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the PR process. Prepare a source checkout without creating a runtime sandbox: ```bash ./scripts/dev-setup.sh ``` Or ask a compatible coding agent to use the repository's contributor-onboarding skill: > Set up this machine as a NemoClaw contributor and prepare it for a first PR. The contributor path is separate from the end-user installer above. The default and `--repair` modes change only repository-local dependencies, builds, and hooks. Use `./scripts/dev-setup.sh --expose-cli` only when you explicitly want a host-visible development CLI. Use `./scripts/dev-setup.sh --with-runtime` only when your change needs sandbox validation; that approved flow also opts into CLI exposure. ## Security NVIDIA takes security seriously. If you discover a vulnerability in NemoClaw, **DO NOT open a public issue.** Use one of the private reporting channels described in [SECURITY.md](SECURITY.md): - Submit a report through the [NVIDIA Vulnerability Disclosure Program](https://www.nvidia.com/en-us/security/report-vulnerability/). - Send an email to [psirt@nvidia.com](mailto:psirt@nvidia.com) encrypted with the [NVIDIA PGP key](https://www.nvidia.com/en-us/security/pgp-key). - Use [GitHub's private vulnerability reporting](https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/configuring-private-vulnerability-reporting-for-a-repository) to submit a report directly on this repository. For security bulletins and PSIRT policies, visit the [NVIDIA Product Security](https://www.nvidia.com/en-us/security/) portal. ## Current Priorities NemoClaw's current priorities are maintained here as a public orientation point for contributors and community members. This list is not a delivery commitment, support promise, or fixed roadmap; priorities can change as maintainers respond to security, quality, platform readiness, and community feedback. - Improve install and onboarding reliability across tested platforms. - Strengthen sandbox hardening, credential handling, and network-policy defaults. - Validate local and routed inference behavior for supported provider paths. - Keep documentation, troubleshooting guidance, and agent skills aligned with supported workflows. For specific scoped work, use [GitHub Issues](https://github.com/NVIDIA/NemoClaw/issues) and start broader proposals in [GitHub Discussions](https://github.com/NVIDIA/NemoClaw/discussions). Security vulnerabilities must use the private reporting channels in [SECURITY.md](SECURITY.md), not public issues. ## Notice and Disclaimer This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk. ## License Apache 2.0. See [LICENSE](LICENSE). --- ## File: docs/about/ecosystem.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Ecosystem" sidebar-title: "Ecosystem" description-agent: "Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell." keywords: ["nemoclaw ecosystem", "openclaw openshell", "nemoclaw vs openshell", "sandboxed openclaw"] content: type: "concept" agent-variants: ["openclaw"] --- NemoClaw provides onboarding, lifecycle management, and OpenClaw operations in OpenShell containers. This page explains how these projects fit together, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [OpenClaw](https://openclaw.ai), and when to choose NemoClaw or OpenShell directly. ## How the Stack Fits Together A NemoClaw deployment for OpenClaw combines three pieces with distinct scopes: OpenClaw, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid flowchart TB NC["🦞 NVIDIA NemoClawCLI, plugin, blueprint"] OS["🐚 NVIDIA OpenShellGateway, policy, inference routing"] OC["🦞 OpenClawAssistant in sandbox"] NC -->|orchestrates| OS OS -->|isolates and runs| OC 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 OC nvDark linkStyle 0 stroke:#76b900,stroke-width:2px linkStyle 1 stroke:#76b900,stroke-width:2px ``` NemoClaw sits above OpenShell in the operator workflow. It calls OpenShell APIs and CLI commands to create and configure the sandbox that runs OpenClaw. Models and endpoints sit behind OpenShell's inference routing. NemoClaw onboarding connects your provider choice to that route. The following table shows the scope of each component in the stack. | Project | Scope | |---------|--------| | [OpenClaw](https://openclaw.ai) | The assistant: runtime, tools, memory, and behavior inside the container. It does not define the sandbox or the host gateway. | | [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | | NemoClaw | The NVIDIA reference stack on the host: `nemoclaw` CLI, OpenClaw plugin, versioned blueprint, managed inference and Model Context Protocol (MCP) servers, messaging-channel setup, host readiness reporting, and lifecycle operations. | ## 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 blueprint encodes a hardened image, default policies, and orchestration so `nemoclaw onboard` can create a tested OpenClaw-on-OpenShell setup with less custom integration work. | | **OpenShell path** | You use OpenShell as the platform and supply your own container, OpenClaw install steps, policy YAML, provider setup, and host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond the OpenShell Community Sandbox OpenShell ships a community sandbox for OpenClaw. Running `openshell sandbox create --from openclaw` pulls that package, builds the image, applies the bundled policy, and starts a working sandbox. This path produces a running OpenClaw environment with OpenShell isolation. NemoClaw builds on that foundation with additional security hardening, automation, and lifecycle tooling. The following table compares the two paths. | Capability | `openshell sandbox create --from openclaw` | `nemoclaw onboard` | |---|---|---| | Sandbox isolation | Yes. OpenShell applies seccomp filters, Landlock filesystem restrictions, privilege dropping, network namespace isolation, and no-new-privileges enforcement. The community sandbox bundles its own policy tailored for OpenClaw. | Yes. NemoClaw applies these through the blueprint and layers a more restrictive policy on top (refer to rows below). | | Credential handling | OpenShell's provider system replaces real credentials with placeholder tokens in the sandbox environment. The L7 proxy resolves placeholders to real values at egress. You create providers manually with `openshell provider create`. | NemoClaw creates OpenShell providers automatically during onboarding. It also filters sensitive host environment variables (provider API keys, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`) from the sandbox creation command to prevent accidental leakage through build args. | | Image hardening | The community image includes standard system tools for general-purpose use. | NemoClaw removes build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | | Filesystem policy | The community sandbox bundles a policy for OpenClaw. | NemoClaw defines a targeted read-only and read-write layout. System paths (`/usr`, `/lib`, `/etc`) are read-only. The agent's home directory (`/sandbox`) and config directory (`/sandbox/.openclaw`) are writable by default so the agent can manage config, install skills, and write to standard paths. | | Inference setup | The community sandbox includes an `openclaw-start` script that runs OpenClaw's onboarding wizard inside the sandbox. You can also create providers and configure OpenShell inference routing manually from the host. | NemoClaw validates the selected provider and model from the host, configures the OpenShell inference route, and writes the managed OpenClaw model reference. Provider credentials stay outside the sandbox. | | Managed MCP | You register providers, network policy, and OpenClaw MCP configuration yourself. | NemoClaw manages authenticated HTTPS Streamable HTTP MCP server lifecycle, ownership records, policy, and credential placeholders through host-side commands. | | Channel messaging | OpenShell provides the credential provider system and L7 proxy for channel traffic. You create providers and configure OpenClaw channel settings manually. | NemoClaw configures supported channels during onboarding or through lifecycle commands. Some experimental webhook channels also require a route-restricted host-side public endpoint. | | Blueprint versioning | No blueprint. The community sandbox uses the published image version. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Repeated onboarding uses the selected blueprint and recorded configuration; host and platform differences can still affect the result. | | Lifecycle state | Not included. | NemoClaw records lifecycle progress, preserves manifest-declared state across rebuilds, and supports snapshot and restore with credential stripping and integrity checks. | | Host readiness and operations | You inspect host prerequisites and operate OpenShell resources directly. | NemoClaw provides read-only host readiness reporting, sandbox status and logs, recovery guidance, rebuild, snapshot, restore, and uninstall workflows. | | Process count limits | OpenShell applies seccomp and privilege dropping. You set process count limits manually with `--ulimit` or orchestrator configuration. | NemoClaw applies a best-effort `ulimit -u 512` in the container entrypoint. Refer to the platform and hardening guidance for hosts that cannot enforce the complete control set. | ## When to Use Which Use the following table to choose NemoClaw or OpenShell. | Situation | Prefer | |-----------|--------| | You want OpenClaw with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw | | You need maximum flexibility for custom images, a layout that does not match the NemoClaw blueprint, or a workload outside this reference stack. | OpenShell with your own integration | | You are standardizing on the NVIDIA reference for always-on assistants with policy and inference routing. | NemoClaw | | You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) | ## Related Topics - [Overview](overview) defines NemoClaw's capabilities, benefits, and use cases. - [How It Works](how-it-works) describes how NemoClaw runs, including the plugin, blueprint, sandbox creation, routing, and protection layers. - [Architecture](../reference/architecture) shows the repository structure and technical diagrams. - [Platform Support](../reference/platform-support) lists current support status and limitations. - [About Managed MCP Servers](../manage-sandboxes/mcp-servers/about-managed-mcp-servers) explains the managed MCP security and lifecycle boundary. - [Community Solutions](../resources/community-contributions) explains how to contribute community-driven examples, showcases, and complete blueprint patterns. --- ## File: docs/about/ecosystem-deepagents.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Ecosystem" sidebar-title: "Ecosystem" description-agent: "Explains how LangChain Deep Agents Code, OpenShell, and NemoClaw fit together, what NemoClaw adds for the managed dcode path, and when to use NemoClaw versus custom OpenShell integration. Use when users ask how Deep Agents relates to NemoClaw and OpenShell." keywords: ["nemoclaw deep agents ecosystem", "dcode openshell sandbox", "nemo-deepagents", "langchain deep agents code"] content: type: "concept" agent-variants: ["deepagents"] --- NemoClaw provides onboarding, lifecycle management, policy, and inference routing for LangChain Deep Agents Code in OpenShell containers. Use the `nemo-deepagents` CLI alias when you work from the Deep Agents guide; it is equivalent to `nemoclaw` with `langchain-deepagents-code` pre-selected. This page explains how Deep Agents, OpenShell, and NemoClaw fit together, and when to choose NemoClaw or a custom OpenShell integration. ## How the Stack Fits Together A NemoClaw deployment for Deep Agents combines three pieces with distinct scopes: LangChain Deep Agents Code, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid flowchart TB NC["NVIDIA NemoClawCLI, blueprint, managed runtime"] OS["NVIDIA OpenShellGateway, policy, inference routing"] DA["LangChain Deep Agents Codedcode terminal agent in sandbox"] NC -->|orchestrates| OS OS -->|isolates and runs| DA classDef nv fill:#76b900,stroke:#333,color:#fff classDef nvDark fill:#333,stroke:#76b900,color:#fff class NC nv class OS nv class DA nvDark linkStyle 0 stroke:#76b900,stroke-width:2px linkStyle 1 stroke:#76b900,stroke-width:2px ``` NemoClaw sits above OpenShell in the operator workflow. It calls OpenShell APIs and CLI commands to create and configure the sandbox that runs `dcode`. Models and endpoints sit behind OpenShell's inference routing. NemoClaw onboarding connects your provider choice to that route and writes the managed Deep Agents configuration under `/sandbox/.deepagents`. The following table shows the scope of each component in the stack. | Project | Scope | |---------|--------| | LangChain Deep Agents Code | The terminal coding agent runtime, interactive TUI, headless `dcode -n` mode, skills, memory, and tool approval UI inside the container. | | OpenShell | The execution environment: sandbox lifecycle, network, filesystem, process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. | | NemoClaw | The NVIDIA reference stack on the host: `nemo-deepagents` and `nemoclaw` CLI paths, versioned blueprint, managed Deep Agents integration layer, managed inference and Model Context Protocol (MCP) servers, host readiness reporting, trace export, and lifecycle operations. | ## 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 Deep Agents blueprint encodes the image, managed `dcode` launchers, default policies, inference configuration, and state handling so `nemo-deepagents onboard` creates a tested Deep Agents-on-OpenShell setup with less custom integration work. | | **OpenShell path** | You use OpenShell as the platform and supply your own container, Deep Agents install steps, policy YAML, provider setup, and runtime wrappers. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond Custom OpenShell You can run Deep Agents 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 Deep Agents. The following table compares custom OpenShell integration with `nemo-deepagents onboard`. | Capability | Custom OpenShell + Deep Agents | `nemo-deepagents onboard` | |---|---|---| | Sandbox isolation | You define and apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges policy. | NemoClaw applies the managed Deep Agents policy through the blueprint and requires the runtime checks that the managed agent runtime depends on. | | Credential handling | You create OpenShell providers manually and decide how `dcode` receives endpoint credentials. | NemoClaw creates OpenShell providers during onboarding, points Deep Agents at `https://inference.local/v1`, and keeps provider credentials outside the sandbox. | | Image hardening | Depends on your base image and install steps. | NemoClaw installs the pinned Deep Agents Code package in `/opt/venv`, uses managed launchers, and rejects unsupported runtime paths such as unmanaged MCP autoloading, nested sandbox providers, and alternate model routes. | | Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths are read-only, `/sandbox` and `/tmp` are writable, and Deep Agents state lives under `/sandbox/.deepagents`. | | Inference setup | You configure OpenShell inference routing and Deep Agents provider settings manually. | NemoClaw validates the selected provider from the host, configures the OpenShell route, and writes `/sandbox/.deepagents/config.toml` for the managed OpenAI-compatible path. | | Managed MCP | You decide how MCP servers enter the sandbox and how they receive credentials. | NemoClaw manages authenticated HTTPS Streamable HTTP MCP server lifecycle, ownership records, policy, credential placeholders, and the Deep Agents MCP projection through host-side commands. | | Optional integrations | You decide how web search, tracing, and other integrations enter the sandbox. | NemoClaw supports an explicit Tavily policy and credential path plus opt-in bounded trace export to an operator-managed host collector. Native LangSmith tracing and ambient OpenTelemetry exporter configuration remain disabled inside the sandbox. | | 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. | | Lifecycle state | Not included unless you build it. | NemoClaw preserves manifest-declared Deep Agents state and omits credential-bearing user files from snapshots and rebuilds. | | Host readiness and operations | You inspect host prerequisites and operate OpenShell resources directly. | NemoClaw provides read-only host readiness reporting, sandbox status and logs, recovery guidance, rebuild, snapshot, restore, and uninstall workflows. | ## When to Use Which Use the following table to choose NemoClaw or custom OpenShell integration. | Situation | Prefer | |-----------|--------| | You want Deep Agents with NVIDIA defaults, managed inference routing, and the documented install and onboard flow. | NemoClaw (`nemo-deepagents`) | | You need maximum flexibility for custom images, a layout that does not match the NemoClaw Deep Agents blueprint, or an unsupported Deep Agents extension path. | OpenShell with your own integration | | You are standardizing on a managed terminal coding agent with sandbox policy and OpenShell-managed credentials. | NemoClaw (`nemo-deepagents`) | | You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell and your orchestration | ## Related Topics - [Overview](overview) defines NemoClaw's capabilities, benefits, and use cases. - [Architecture Overview](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Deep Agents. - [Architecture Details](../reference/architecture) describes the Deep Agents blueprint, file layout, policy paths, and managed runtime internals. - [Platform Support](../reference/platform-support) lists current support status and limitations. - [About Managed MCP Servers](../manage-sandboxes/mcp-servers/about-managed-mcp-servers) explains the managed MCP security and lifecycle boundary. - [Understand Deep Agents Trace Export](../monitoring/understand-deepagents-trace-export) explains the managed trace data and receiver trust boundaries. - [Quickstart with Deep Agents](../get-started/quickstart) installs NemoClaw and launches your first Deep Agents sandbox. - [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) explains provider choices and the `inference.local` route. - [Deep Agents Code overview](https://docs.langchain.com/oss/python/deepagents/code/overview) explains upstream `dcode` capabilities and commands. - [Community Solutions](../resources/community-contributions) explains how to contribute community-driven examples, showcases, and complete blueprint patterns. --- ## File: docs/about/ecosystem-hermes.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Ecosystem" sidebar-title: "Ecosystem" 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" agent-variants: ["hermes"] --- NemoClaw provides onboarding, lifecycle management, and Hermes operations in OpenShell containers. Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected. This page explains how these projects fit together, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and when to choose NemoHermes or OpenShell directly. ## How the Stack Fits Together A NemoClaw deployment for Hermes combines three pieces with distinct scopes: Hermes, OpenShell, and NemoClaw. The following diagram shows how they fit together. ```mermaid flowchart TB NC["🦞 NVIDIA NemoClawCLI, blueprint"] OS["🐚 NVIDIA OpenShellGateway, policy, inference routing"] HM["HermesAgent 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 calls OpenShell APIs and CLI commands to create and configure the sandbox that runs Hermes. Models and endpoints sit behind OpenShell's inference routing. NemoClaw onboarding connects your provider choice to that route, including the Hermes Provider route when you onboard through `nemohermes`. The following table shows the scope of each component in the stack. | 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` and `nemoclaw` CLI paths, versioned blueprint, managed inference and Model Context Protocol (MCP) servers, messaging-channel setup, host readiness reporting, and lifecycle operations. | ## 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 create a tested Hermes-on-OpenShell setup with less custom integration work. | | **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. | ## What NemoClaw Adds Beyond Custom OpenShell 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 custom OpenShell integration with `nemohermes onboard`. | Capability | Custom OpenShell + Hermes | `nemohermes onboard` | |---|---|---| | Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. | | Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. | | Image hardening | Depends on your base image and install steps. | NemoClaw removes build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. | | Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. | | Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates the selected provider and model from the host, configures the OpenShell route, and writes the managed model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. | | Managed MCP | You register providers, network policy, and Hermes MCP configuration yourself. | NemoClaw manages authenticated HTTPS Streamable HTTP MCP server lifecycle, ownership records, policy, and credential placeholders through host-side commands. | | Channel messaging | OpenShell delivers channel credentials through its provider system and L7 proxy. You configure Hermes platform adapters manually. | NemoClaw configures supported channels during onboarding or through lifecycle commands and writes the managed Hermes channel settings. | | 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. Repeated onboarding uses the selected blueprint and recorded configuration; host and platform differences can still affect the result. | | Lifecycle state | Not included unless you build it. | NemoClaw records lifecycle progress, preserves manifest-declared Hermes state across rebuilds, and supports snapshot and restore without copying `auth.json`. | | Host readiness and operations | You inspect host prerequisites and operate OpenShell resources directly. | NemoClaw provides read-only host readiness reporting, sandbox status and logs, recovery guidance, rebuild, snapshot, restore, and uninstall workflows. | | Process count limits | You set process count limits manually with `--ulimit` or orchestrator configuration. | NemoClaw applies a best-effort `ulimit -u 512` in the container entrypoint. Refer to the platform and hardening guidance for hosts that cannot enforce the complete control set. | ## When to Use Which Use the following table to choose NemoHermes or OpenShell. | 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](overview) defines NemoClaw's capabilities, benefits, and use cases. - [How It Works](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes. - [Architecture](../reference/architecture) shows the repository structure and technical diagrams. - [Platform Support](../reference/platform-support) lists current support status and limitations. - [About Managed MCP Servers](../manage-sandboxes/mcp-servers/about-managed-mcp-servers) explains the managed MCP security and lifecycle boundary. - [Quickstart with Hermes](../get-started/quickstart) installs NemoClaw and launches your first Hermes sandbox. - [Community Solutions](../resources/community-contributions) explains how to contribute community-driven examples, showcases, and complete blueprint patterns. --- ## File: docs/about/how-it-works.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "NemoClaw Architecture Overview" sidebar-title: "Architecture Overview" description-agent: "Describes how NemoClaw works internally: host CLI, agent integration layer, blueprint runner, OpenShell orchestration, lifecycle state, managed integrations, 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", "nemoclaw managed mcp architecture"] content: type: "concept" --- This page explains how NemoClaw runs supported agent runtimes inside OpenShell sandboxes. It covers the host CLI, OpenShell gateway, agent integration layer, lifecycle state, managed Model Context Protocol (MCP) servers and other integrations, and protection layers. NemoClaw does not replace OpenShell or the selected agent runtime. It packages them as a repeatable setup with a versioned blueprint, agent-specific configuration, managed inference, network policy, and lifecycle operations. ## High-Level Flow NemoClaw keeps operator control on the host while OpenShell enforces the sandbox boundary. The OpenShell gateway coordinates sandbox lifecycle, credentials, network policy, inference routes, and approved integration traffic. ```mermaid flowchart LR USERS["Users and operators"]:::users CLI["NemoClaw host CLIinstall, probe, onboard, operate"]:::control GATEWAY["OpenShell gatewaylifecycle, credentials, policy, routing"]:::gateway SANDBOX["OpenShell sandboxagent runtime and integration layer"]:::sandbox INTERFACE["Agent interfaceruntime-specific interaction path"]:::users STATE["Managed state and artifactsregistry, workspace, policy records, snapshots"]:::state INFERENCE["Inference providerssupported hosted or local inference"]:::inference INTEGRATIONS["Approved integrationsMCP servers and package services"]:::integrations USERS -->|"operate"| CLI CLI -->|"configure resources"| GATEWAY GATEWAY -->|"create and control"| SANDBOX SANDBOX -->|"managed requests"| GATEWAY GATEWAY -->|"routed inference"| INFERENCE GATEWAY -->|"approved egress"| INTEGRATIONS USERS -->|"interact"| INTERFACE INTERFACE --> SANDBOX CLI -->|"record lifecycle"| STATE SANDBOX -.->|"persist declared state"| STATE classDef users fill:#d9ecf7,stroke:#6aa6c8,color:#1a1a1a,stroke-width:2px classDef control fill:#d7f0dc,stroke:#5a9f70,color:#1a1a1a,stroke-width:2px classDef gateway fill:#fff1be,stroke:#c4992f,color:#1a1a1a,stroke-width:2px classDef sandbox fill:#e7ddff,stroke:#8c6ccf,color:#1a1a1a,stroke-width:2px classDef state fill:#f7dfe4,stroke:#c86d7d,color:#1a1a1a,stroke-width:2px classDef inference fill:#d5f1f1,stroke:#4fa7a7,color:#1a1a1a,stroke-width:2px classDef integrations fill:#fce6d7,stroke:#c77e55,color:#1a1a1a,stroke-width:2px ``` The diagram has the following components: | Component | Role in the flow | |-------|------------------| | Users and operators | Install and operate NemoClaw from the host, then interact through the selected agent interface. | | NemoClaw host CLI | Collects configuration, runs readiness checks and onboarding, resolves the blueprint, and operates managed resources. | | OpenShell gateway | Coordinates sandbox lifecycle, credentials, networking, policy enforcement, inference routing, and approved integration egress. | | OpenShell sandbox | Runs the selected agent runtime with its NemoClaw integration layer, configuration, and supporting tools. | | Agent interface | Provides the interaction path exposed by the selected agent runtime. | | Inference providers | Receive managed inference requests through the OpenShell gateway. | | Approved integrations | Receive policy-approved requests to MCP servers, package indexes, and other configured services. | | Managed state and artifacts | Preserve registry records, workspace files, policy records, logs, and manifest-declared snapshot content across supported lifecycle operations. | For repository layout, file paths, and deeper diagrams, refer to [Architecture](../reference/architecture). ## Design Principles NemoClaw follows these architecture principles. Versioned blueprint : The blueprint runner resolves a versioned blueprint and verifies its digest before it changes managed resources. Host credential custody : OpenShell stores inference provider credentials and managed MCP bearer values outside the sandbox and replaces placeholders at approved request boundaries. Agent-specific integration : Each supported agent runtime receives the configuration, wrappers, plugin, or adapter required for its documented workflow. Resumable lifecycle : NemoClaw records lifecycle progress and reconciles managed resources after supported interruptions or partial operations. Manifest-declared state : Rebuild, snapshot, and restore operations preserve only the state declared for the selected agent runtime. Each agent manifest and operation defines which credential-bearing files to exclude. Host-configured messaging credentials also use OpenShell credential delivery. Some messaging integrations, such as QR-paired WhatsApp, retain explicitly declared session credentials inside the sandbox so supported lifecycle operations can preserve them. ## CLI, Integration Layer, and Blueprint NemoClaw separates host orchestration, agent-specific behavior, and sandbox definition. - The _host CLI_ runs readiness checks and onboarding, validates provider choices, records lifecycle state, and operates OpenShell resources. - The _OpenClaw integration layer_ includes a TypeScript plugin that runs inside the sandbox. It registers the managed inference provider metadata, the `/nemoclaw` slash command, and runtime context hooks. Runtime context is prepended as system guidance, so sandbox and policy instructions stay active without appearing in the visible chat transcript. - The _Hermes integration layer_ writes runtime configuration under `/sandbox/.hermes`, including `config.yaml`, environment files, and supported messaging-channel settings. - The _Deep Agents integration layer_ writes managed runtime configuration under `/sandbox/.deepagents`. It includes `config.toml`, managed MCP projection state, and the inference route used by `dcode`. - The _blueprint_ is a versioned YAML package with the sandbox image, agent manifest, network policy, inference profile, and supporting assets. The runner resolves and verifies the blueprint before applying it through OpenShell. This separation keeps host orchestration, agent-specific assets, and the sandbox definition at explicit lifecycle boundaries. ## Readiness and Sandbox Creation Run `$$nemoclaw host probe` when you need a read-only system readiness report before onboarding. The report combines host and gateway observations, capabilities, qualifications, findings, evidence, and CLI provenance without changing system state. Onboarding consumes the same stable host and gateway entities and applies its explicit admission policy. It revalidates live facts after permitted preparation and when a saved onboarding session resumes. When you run `$$nemoclaw onboard`, the host CLI and blueprint runner complete these operations: 1. NemoClaw resolves gateway lifecycle authority and rejects blocking system readiness results before managed resource effects. A container-backed WSL GPU proof can run only after this admission check; explicit CPU-only intent skips it. 2. NemoClaw resolves the blueprint, checks version compatibility, and verifies the digest. 3. Onboarding validates the selected inference provider, credentials, agent settings, and platform requirements. 4. The runner determines which gateway, provider, policy, sandbox, and integration resources to create or update. 5. NemoClaw records progress so a supported interruption can resume or report a specific recovery action. After the sandbox starts, the selected agent uses its managed configuration and the controls supported by the host. ## Lifecycle and State NemoClaw operates the sandbox and its manifest-declared state through host-side commands. | Operation | Result | |---|---| | Inspect | `host probe`, `status`, and `logs` report system, sandbox, agent-runtime, inference, and recovery information without replacing the sandbox. | | Configure | Inference, policy, managed MCP, and supported agent-runtime integration commands update the applicable managed resources. | | Rebuild | Recreates the sandbox from the recorded configuration and restores supported agent state through a recorded transaction. | | Recover | Repairs a stopped or degraded agent runtime and its sandbox-scoped forwards when the recorded identities still match. | | Snapshot and restore | Captures manifest-declared state with the agent- and operation-specific credential exclusions, then applies that state to an eligible sandbox. | | Destroy and uninstall | Removes the selected sandbox or host installation according to the command scope and preservation choices. | Refer to [Recover and Rebuild Sandboxes](../manage-sandboxes/operate-sandboxes/recover-and-rebuild-sandboxes) and [Create and Restore Snapshots](../manage-sandboxes/state-and-backups/create-and-restore-snapshots) for lifecycle details. ## Inference Routing Managed agent runtimes send model requests to `inference.local` instead of an upstream endpoint. During onboarding, NemoClaw validates the selected provider and model, configures the OpenShell inference route, and writes the matching model reference into the managed agent configuration. OpenShell keeps the provider credential outside the sandbox and sends approved requests to the upstream endpoint. When you select the Model Router provider, `inference.local` routes to a host-side router that chooses from the configured NVIDIA model pool for each request. For Hermes, `$$nemoclaw inference set` updates `/sandbox/.hermes/config.yaml` at runtime without rebuilding the sandbox. For Deep Agents, the managed `dcode` runtime reads the OpenAI-compatible route that NemoClaw writes into `/sandbox/.deepagents/config.toml`. ## Managed Integrations NemoClaw connects supported external services through OpenShell providers, network policy, and agent-specific adapters. Managed MCP supports authenticated HTTPS Streamable HTTP MCP servers for OpenClaw, Hermes, and Deep Agents Code. NemoClaw stores the credential name and ownership metadata, while OpenShell stores the raw value outside the sandbox. The agent adapter receives a credential placeholder that OpenShell replaces only at the approved egress boundary. Messaging channels use agent-specific channel manifests, credential delivery, network policy, and lifecycle commands. Some experimental webhook channels also require a route-restricted host-side public endpoint. Refer to [Choose Messaging Channels](../manage-sandboxes/messaging-channels/choose-messaging-channels) for agent and channel status. Deep Agents Code can also opt into bounded trace export to an operator-managed host collector. Native LangSmith tracing and ambient OpenTelemetry exporter configuration remain disabled inside the sandbox. Refer to [Understand Deep Agents Trace Export](../monitoring/understand-deepagents-trace-export) for the data and receiver trust boundaries. Refer to [About Managed MCP Servers](../manage-sandboxes/mcp-servers/about-managed-mcp-servers) for the managed MCP security and lifecycle design. ## Protection Layers The sandbox starts with a baseline policy that controls network egress, filesystem access, process privileges, and inference routing. | Layer | What it protects | When it applies | |---|---|---| | Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. | | Filesystem | Restricts system paths to read-only; `/sandbox` and `/tmp` are writable. | Locked at sandbox creation. | | Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | When the agent tries to reach an unapproved host, OpenShell blocks the request and surfaces it in the terminal user interface (TUI) for operator approval. Approved endpoints persist within the current sandbox instance but are not saved to the baseline policy file. NemoClaw's runtime context tells supported agents to try allowed network and filesystem actions first, then report whether policy denial, DNS, timeout, TLS, or filesystem access caused a failure. Host and platform limitations can change how individual controls apply. Refer to [Platform Support](../reference/platform-support) and [Security Best Practices](../security/best-practices) before you treat a control as an environment-wide guarantee. ## Next Steps - 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. - Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. - Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for detailed provider configuration. - Read [Network Policies](../reference/network-policies) for baseline rules and runtime changes. - Read [Review Sandbox Hardening](../manage-sandboxes/configure-sandboxes/review-sandbox-hardening) for container-level controls and limitations. - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths. - Follow [Quickstart with Hermes](../get-started/quickstart) to launch your first sandbox. - Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. - Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for detailed provider configuration. - Read [Network Policies](../reference/network-policies) for baseline rules and runtime changes. - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths. - Follow [Quickstart with Deep Agents](../get-started/quickstart) to launch your first sandbox. - Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle. - Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for detailed provider configuration. - Read [Network Policies](../reference/network-policies) for baseline rules and runtime changes. --- ## File: docs/about/overview.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Overview of NVIDIA NemoClaw" sidebar-title: "Overview" 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", "langchain deep agents code", "dcode sandbox", "nvidia openshell", "nvidia nemotron"] content: type: "concept" skill: priority: 10 --- NVIDIA NemoClaw is an open-source reference stack for running always-on AI agents more safely inside OpenShell containers. NVIDIA NemoClaw is an open-source reference stack for running AI coding agents more safely inside OpenShell containers. NemoClaw provides onboarding, lifecycle management, and agent operations for supported agent runtimes in OpenShell sandboxes. It combines a host CLI, a versioned blueprint, and an agent-specific integration layer. The OpenShell gateway coordinates sandbox lifecycle, managed inference, credentials, and policy enforcement. The primary tested platforms are Linux and DGX Spark. NemoClaw also documents platform limitations for macOS, Windows Subsystem for Linux (WSL), DGX Station, and headless Linux servers. Refer to [Platform Support](../reference/platform-support) for current agent, platform, provider, integration, and deployment-path status. ## What NemoClaw Provides NemoClaw groups its supported capabilities around running, connecting, controlling, and operating agents. | Area | Capability | |---|---| | Run supported agents | Onboards OpenClaw, Hermes, or LangChain Deep Agents Code into an agent-specific sandbox image and configuration. | | Route inference | Connects supported hosted inference and local inference providers through `inference.local`. OpenShell keeps provider credentials outside the sandbox. | | Control sandbox access | Applies network policy, filesystem policy, process controls, and managed inference through OpenShell. | | Operate the lifecycle | Reports host readiness, creates or updates sandboxes, reports status and logs, rebuilds or recovers sandboxes, and creates or restores snapshots. | | Connect Model Context Protocol (MCP) servers | Manages authenticated HTTPS Streamable HTTP MCP servers for all supported agent runtimes. OpenShell replaces credential placeholders at approved egress boundaries. | | Extend agent workflows | Installs agent skills and publishes Markdown documentation that coding agents can use for setup, operation, security review, and troubleshooting. | | Connect messaging channels | Configures supported messaging channels during onboarding or through lifecycle commands. Availability and maturity vary by agent and channel. | | Configure web search | Configures a supported Brave Search or Tavily Search path and keeps the service credential outside the sandbox. Provider availability varies by agent. | | Operate a terminal agent | Runs the managed `dcode` terminal agent interactively or through its headless JSON workflow. | | Export traces | Optionally sends bounded Deep Agents Code traces to an operator-managed host collector. The receiver and exported content require the documented trust controls. | ## Benefits of Using NemoClaw Autonomous AI agents can make arbitrary network requests, access the host filesystem, and call any inference endpoint. Without controls, this creates security, cost, and compliance risks that grow as agents run unattended. NemoClaw provides these controls and lifecycle tools to reduce those risks. | Benefit | Description | |---|---| | Sandboxed execution | Runs each agent in an OpenShell sandbox with documented filesystem, process, and network controls. Enforcement limitations vary by host. | | Credential custody | Keeps inference credentials and managed MCP bearer values outside the sandbox through OpenShell. | | Operator-controlled egress | Uses YAML network policy and policy presets. OpenShell blocks unapproved destinations and surfaces requests for operator review. | | Repeatable lifecycle | Uses versioned, digest-verified blueprints and manifest-declared state to support onboarding, rebuild, recovery, snapshot, and restore operations. | | Agent-specific workflows | Provides dedicated CLI aliases, configuration, lifecycle adapters, documentation, and validation for each supported agent runtime. | Host-configured messaging credentials also use OpenShell credential delivery. QR-paired sessions such as WhatsApp store mutable session credentials in the sandbox and preserve them according to the agent manifest. ## Use Cases Use NemoClaw when you need a supported agent runtime with managed inference, network policy, and lifecycle operations. | Use Case | Description | |---|---| | Controlled agent evaluation | Test agent behavior with explicit filesystem and network boundaries before you add more access. | | Managed tool access | Connect authenticated MCP servers without storing raw service credentials in agent configuration. | | Headless server deployment | Run a sandboxed agent on a remote Linux server through SSH. Refer to [Deploy to a Headless Server](../deployment/deploy-to-headless-server). | | Always-on messaging agent | Connect a supported messaging channel to an agent with channel-specific credentials, policy, and lifecycle management. | | Terminal coding agent | Run `dcode` inside an OpenShell sandbox with OpenShell-managed inference credentials and a managed terminal workflow. | ## Product Scope NemoClaw is an early-preview reference stack for a trusted operator on one host. It is not a hosted NemoClaw service, a multi-tenant enterprise control plane, or an enterprise identity system. Refer to [Enterprise Readiness](../reference/enterprise-readiness) for supported, manual, platform-owned, roadmap-only, and out-of-scope capabilities. ## Next Steps Use these topics to learn more about NemoClaw and how to install and use it. - Read [Platform Support](../reference/platform-support) before you repeat an agent, platform, provider, integration, or deployment claim. - Read [Architecture Overview](how-it-works) to understand the host CLI, integration layer, blueprint, OpenShell gateway, and sandbox lifecycle. - Read [About Managed MCP Servers](../manage-sandboxes/mcp-servers/about-managed-mcp-servers) for the managed MCP security and lifecycle boundary. - Read [System Readiness](../reference/system-readiness) to inspect a host before onboarding without changing host state. - Read [Use NemoClaw Docs with Your Coding Agents](../resources/agent-skills) to give an AI coding agent the NemoClaw Markdown documentation entry points. - Read [Ecosystem](ecosystem) to understand how your agent, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. - Follow [Quickstart with OpenClaw](../get-started/quickstart) to install NemoClaw and run your first OpenClaw sandbox. - Read [Choose Messaging Channels](../manage-sandboxes/messaging-channels/choose-messaging-channels) before you enable a messaging channel. - Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) to check the inference providers that NemoClaw supports and how inference routing works. - Read [Ecosystem](ecosystem) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. - Follow [Quickstart with Hermes](../get-started/quickstart) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`. - Read [Choose Messaging Channels](../manage-sandboxes/messaging-channels/choose-messaging-channels) before you enable a messaging channel. - Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) to check the inference providers that NemoClaw supports and how inference routing works. - Read [Ecosystem](ecosystem) to understand how Deep Agents, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell. - Follow [Quickstart with Deep Agents](../get-started/quickstart) to install NemoClaw and run your first Deep Agents sandbox with `$$nemoclaw`. - Read [Understand Deep Agents Trace Export](../monitoring/understand-deepagents-trace-export) before you enable managed trace export. - Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) to check the inference providers that NemoClaw supports and how inference routing works. --- ## File: docs/configure-agents/configure-agent-heartbeats.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Configure OpenClaw Agent Heartbeats" sidebar-title: "Configure Agent Heartbeats" description-agent: "Configures OpenClaw heartbeat cadence through NemoClaw onboarding. Use when changing periodic agent wake-ups or disabling heartbeat instructions." keywords: ["nemoclaw heartbeat", "openclaw heartbeat", "HEARTBEAT.md"] content: type: "how_to" agent-variants: ["openclaw"] --- OpenClaw heartbeats run periodic main-session agent turns. Configure their cadence before onboarding or recreating the sandbox. ## Set the Heartbeat Cadence Set `NEMOCLAW_AGENT_HEARTBEAT_EVERY` to a Go-style duration such as `5m` or `2h`. OpenClaw defaults to 30 minutes, or 1 hour for Anthropic OAuth and Claude CLI reuse, when the variable is unset. ```bash export NEMOCLAW_AGENT_HEARTBEAT_EVERY=2h nemoclaw onboard ``` At each interval, the agent wakes to review follow-ups and read `HEARTBEAT.md` when that file exists in the workspace. ## Disable Heartbeats Set the interval to `0m` to disable periodic turns. ```bash export NEMOCLAW_AGENT_HEARTBEAT_EVERY=0m nemoclaw onboard ``` Disabling heartbeats also removes `HEARTBEAT.md` from normal-run bootstrap context according to OpenClaw behavior. The model no longer receives heartbeat-only instructions. ## Apply the Change NemoClaw writes the heartbeat setting into `openclaw.json` during onboarding. Direct `openclaw config set` changes are not the supported path for this NemoClaw-managed build-time default, and a rebuild overwrites direct file edits. Recreate an existing sandbox to apply a new cadence. ```bash nemoclaw onboard --fresh --name --recreate-sandbox ``` --- ## File: docs/configure-agents/progressive-tool-disclosure.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Configure Progressive Tool Disclosure" sidebar-title: "Progressive Tool Disclosure" description-agent: "Explains progressive tool disclosure for OpenClaw, Hermes, and Deep Agents Code. Use when configuring Tool Search, search_tools, result limits, or direct disclosure." keywords: ["nemoclaw tool disclosure", "progressive tool disclosure", "search_tools", "Tool Search"] content: type: "how_to" --- Progressive tool disclosure limits the tool schemas placed in the model's initial context. Each supported agent keeps its native discovery mechanism and configuration schema. ## Compare Agent Behavior The keys, tool names, and result limits are not interchangeable across agents. | Agent | NemoClaw-generated mechanism | Default results | Maximum results | |---|---|---:|---:| | OpenClaw | `tools.toolSearch.mode: "tools"` with `searchDefaultLimit` and `maxSearchLimit` | 8 | 20 | | Hermes | `tools.tool_search.enabled: "on"` with `search_default_limit` and `max_search_limit` | 5 | 20 | | Deep Agents Code | NemoClaw `ProgressiveToolDisclosureMiddleware` and the `search_tools` model tool | Up to 20 | 20 | Progressive disclosure changes model context, not authorization. Final tool calls still use the agent's normal execution, policy, approval, and hook paths. ## Understand OpenClaw Tool Search OpenClaw uses `mode: "tools"` to select its structured bridge instead of the JavaScript-based `tool_search_code` bridge. A model-specific `toolSearch: false` override disables Tool Search entirely. NemoClaw's generated default exposes `tool_search`, `tool_describe`, and `tool_call` through structured Tool Search. Managed Nemotron Super and Ultra routes retain model-specific `toolSearch: false` safeguards and use direct structured tool calling until a live structured-search trajectory clears the replacement. In the model-specific manifest contract, `false` disables Tool Search while `true` selects OpenClaw's default code mode. Neither boolean selects structured mode. ## Understand Hermes Tool Search Hermes uses its native tool-search bridge when `enabled: "on"` and the session has at least one deferrable MCP or non-core plugin tool. Hermes core tools remain directly visible. ## Understand Deep Agents Tool Search Deep Agents Code activates its middleware after at least one MCP tool loads successfully. It initially exposes `search_tools` and the core filesystem, shell, user-input, and todo tools. Each search returns up to 20 name-sorted tools whose names or descriptions match case-insensitively. The graph thread retains up to 64 discovered named tools. Search output is limited to 8 KiB, individual descriptions to 256 characters, individual tool-name representations to 120 bytes, individual named schemas to 16 KiB, and the discovered schemas visible in one model request to 128 KiB. Named tools that exceed the name or schema limits are not discoverable, while core tools remain visible. When a broad query exceeds a result or state limit, `search_tools` reports omitted matches so the model can refine the query. Provider-native definitions without a callable name remain visible because the middleware cannot search or checkpoint them by name. Main-agent and local-subagent discoveries use separate middleware instances. ## Use Direct Disclosure Use direct disclosure when you want to present every registered tool to the model. ```bash $$nemoclaw onboard --tool-disclosure direct ``` You can also set `NEMOCLAW_TOOL_DISCLOSURE=direct` before onboarding. For an existing sandbox with managed MCP servers, rebuild with the direct setting. ```bash $$nemoclaw rebuild --tool-disclosure direct ``` The transactional rebuild preserves MCP providers and adapter state while changing the disclosure mode. An explicit direct selection is authoritative. Model-specific safety settings can disable progressive search for a model, but cannot re-enable it over the direct selection. ## Related Topics - [Troubleshooting](../reference/troubleshooting#tool-calls-appear-as-assistant-text) when the model emits a tool call as assistant text instead of structured output. - [Add an MCP Server](../manage-sandboxes/mcp-servers/add-an-mcp-server) to configure a managed tool source. --- ## File: docs/configure-agents/understand-context-compaction.mdx --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Understand OpenClaw Context Compaction" sidebar-title: "Understand Context Compaction" description-agent: "Explains OpenClaw context compaction behavior in NemoClaw-managed sandboxes. Use when diagnosing long compaction attempts or understanding transcript rotation." keywords: ["nemoclaw context compaction", "openclaw transcript compaction", "openclaw context management"] content: type: "concept" agent-variants: ["openclaw"] --- NemoClaw configures safeguard compaction for OpenClaw sandboxes that use its managed `inference.local` route, except for Local Ollama routes. The safeguard bounds each compaction attempt while leaving summarization behavior under OpenClaw's control. ## Compaction Attempt Limit Each automatic or explicitly requested compaction attempt is limited to 120 seconds. OpenClaw reports progress while the attempt runs. After a successful attempt, OpenClaw rotates the active transcript while preserving the most recent turn. ## Compaction Results The time limit prevents an individual attempt from running indefinitely. It does not guarantee that compaction succeeds or reduces the active context. OpenClaw owns the summarization behavior and decides whether the compacted transcript satisfies its requirements. ## When the Setting Applies NemoClaw generates the safeguard setting when it builds or recreates the sandbox image. Recreate the sandbox when you need a new image to incorporate changed build-time settings. For model context-window and output-token limits, refer to [Configure Model Limits](../inference/manage-inference/configure-model-limits).