Skip to content

docs: simplify README and make landing docs agent-agnostic #4552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
miyoungc merged 3 commits into from
May 29, 2026
Merged

docs: simplify README and make landing docs agent-agnostic #4552

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fc1f879
docs: simplify README and make landing docs agent-agnostic
miyoungc May 29, 2026
c5f186f
docs(readme): restore full documentation index table
miyoungc May 29, 2026
a39b68b
docs(readme): use GitHub note alert and agent list
miyoungc May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
265 changes: 19 additions & 246 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<!-- start-badges -->
[![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)
<!-- end-badges -->

<!-- start-intro -->
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.
<!-- end-intro -->
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/).

<!-- start-quickstart-guide -->
## 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.

<!-- 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 -->

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 <model> --provider <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).

<!-- end-quickstart-guide -->
| 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

Expand All @@ -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)
Expand Down
12 changes: 6 additions & 6 deletions docs/about/how-it-works.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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. |
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Loading
Loading